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INTRODUCTION TO THIS MANUAL 


This manual gives descriptions of the publicly available features of UNIX. It provides neither a 
general overview (see “The UNIX Time-sharing System” for that) nor details of the implementa- 
tion of the system (which remain to be disclosed). 

Within the area it surveys, this manual attempts to be as complete and timely as possible. A 
conscious decision was made to describe each program in exactly the state it was in at the time 
its manual section was prepared. In particular, the desire to describe something as it should be 

not as it is, was resisted. Inevitably, this means that many sections will soon be out of date. 


This manual is divided into eight sections: 

I. 

Commands 

II. 

System calls 

III. 

Subroutines 

IV. 

Special files 

V. 

File formats 

VI. 

User-maintained programs 

VII. 

Miscellaneous 

VIII. 

Maintenance 


Commands are programs intended to be invoked directly by the user, in contradistinction to 
subroutines, which are intended to be called by the user’s programs. Commands generally reside 
in directory /bin (for binary programs). This directory is searched automatically by the command' 
line interpreter. Some programs also reside in /usr/bin, to save space in /bin. Some programs 
classified as commands are located elsewhere; this fact is indicated in the appropriate sections. 

System calls are entries into the UNIX supervisor. In assembly language, they are coded with the 
use of the opcode sys, a synonym for the trap instruction. In this edition, the C language inter- 
face routines to the system calls have been incorporated in section II. 

A small assortment of subroutines is available; they are described in section III. The binary 
form of most of them is kept in the system library lliblliba.a. The subroutines available from C 
and from Fortran are also included; they reside in /lib/libc.a and /lib/libf.a respectively. 

The special files section IV discusses the characteristics of each system “file” which actually 
refers to an I/O device. The names in this section refer to the DEC device names for the 
hardware, instead of the names of the special files themselves. 

The file formats section V documents the structure of particular kinds of files; for example, the 
form of the output of the loader and assembler is given. Excluded are files used by only’ one 
command, for example the assembler’s intermediate files. 

User-maintained programs (section VI) are not considered part of the Unix system, and the prin- 
cipal reason for listing them is to indicate their existence without necessarily giving a complete 
description. The author should be consulted for information. 

The miscellaneous section (VII) gathers odds and ends. 

Section VIII discusses commands which are not intended for use by the ordinary user, in some 
cases because they disclose information in which he is presumably not interested, and in others 
because they perform privileged functions. 

Each section consists of a number of independent entries of a page or so each. The name of the 
entry is in the upper corners of its pages, its preparation date in the upper middle. Entries 
within each section are alphabetized. The page numbers of each entry start at 1. (The earlier 


n 


hope for frequent, partial updates of the manual is clearly in vain, but in any event it is not 
feasible to maintain consecutive page numbering in a document like this.) 

All entries are based on a common format, not all of whose subsections will always appear. 

The name section repeats the entry name and gives a very short description of its pur- 
pose. 

The synopsis summarizes the use of the program being described. A few conventions are 
used, particularly in the Commands section: 

Boldface words are considered literals, and are typed just as they appear. 

Square brackets ( [ ] ) around an argument indicate that the argument is optional. 
When an argument is given as “name”, it always refers to a file name. 

Ellipses are used to show that the previous argument-prototype may be re- 
peated. 

A final convention is used by the commands themselves. An argument begin- 
ning with a minus sign ” is often taken to mean some sort of flag argument 
even if it appears in a position where a file name could appear. Therefore, it is 
unwise to have files whose names begin with ”, 

The description section discusses in detail the subject at hand. 

The files section gives the names of files which are built into the program. 

A see also section gives pointers to related information. 

A diagnostics section discusses the diagnostic indications which may be produced. Mes- 
sages which are intended to be self-explanatory are not listed. 

The bugs section gives known bugs and sometimes deficiencies. Occasionally also tne 
suggested fix is described. 

At the beginning of this document is a table of contents, organized by section and alphabetically 
within each section. There is also a permuted index derived from the table of contents. Within 
each index entry, the title of the writeup to which it refers is followed by the appropriate section 
number in parentheses. This fact is important because there is considerable name duplication 
among the sections, arising principally from commands which exist only to exercise a particular 
system call. 

This manual was prepared using the UNIX text editor ed and the formatting program troff. 
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randdll) random 
factor(VI) discover prime factors of a 
sized) size of an 
reloc(VIH) relocate 
sky(VI) 
odd) 

oprd) 
mand) run 
ibm(Vl) submit 
logind) sign 
dupdl) duplicate an 
fstatdl) get status of 
opendl) 


mode of typewriter 

mode 

mode 

monitordll) prepare execution profile 

moo(VI) guessing game 

mount file system 

mount file system 

mounted file system table 

mountdl) mount file system 

mount(VIlI) mount file system 

move or rename a file 

move read/write pointer 

moving-head disk 

msh(VIII) mini Shell 

mtab(V) mounted file system table. 

multiplexer 

mvd) move or rename a file 
name from UID 
name list 
name list 

name of current typewriter 

name 

name 

name 

nargsdH) argument count 
natural logarithm 

neqnd) typeset mathematics on terminal 
new 11/20 system 
new file 
new process 

niced) run a command at low priority 
nicedl) set program priority 
nlistdH) get entries from name list 
nmd) print name list 

nohupd) run a command immune to hangups 
non-local goto 

npr(VI) print file on Spider line-printer 

nrofld) format text 

number generator 

number 

object file 

object files 

obtain ep'nemerides 

octal dump 

odd) octal dump 

off line print 

off section of UNIX manual 
off-line job to HO IBM 370 
onto UNIX 
open file descriptor 
open file 

open for reading or writing 
opendl) open for reading or writing 
oprd) off line print 
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slly(I) set typewriter 

options 


' rk(IV) RK-11/RK03 

(or RK.05) disk 


ecvt(III) 

output conversion 


locv(III) long 

output conversion 


a.out(V) assembler and link editor 

output 


putc(III) buffered 

output 


chown(I) change 

owner 

\ 

chown(II) change 

owner 

) 

pc(IV) PC-11 

paper tape reader/punch 
passwd(I) set login password 
passwd(V) password file 


crypt(IIl) 

password encoding 


passwd(V) 

password file 


passwdfl) set login 

password 


grep(I) search a file for a 

pattern 


pc(IV) 

PC-11 paper tape reader/punch 
pcdV) PC-11 paper tape reader/punch 

) 

update(VIII) 

periodically update the super block 


mesgQ) 

permit or deny messages 


ptx(VD 

permuted index 

perrordll) system error messages 
pfed) print floating exception 


dpdCVIII) data 

phone daemon 


catdV) 

phototypesetter interface 


catsim(VI) 

phototypesetter simulator 


split® split a file into 

pieces 


tee® 

pipe fitting 



pipedl) create an interprocess channel 
plog(VI) make a graph on the gsi terminal 



plot(Vl) make a graph 


fptrapQII) floating 

point interpreter 


seek(II) move read/write 

pointer 


typo® find 

possible typos 



pow(III) floating exponentiation 


azel(VI) satellite 

predictions 


monitor®!) 

prepare execution profile 
prd) print file 


factor(VI) discover 

prime factors of a number 


dated) 

print and set the date 


cal(VI) 

print calendar 


npr(VI) 

print file on Spider line-printer 

) 

prd) 

print file 

pfed) 

print floating exception 


commd) 

print lines common to two files 


nmd) 

print name list 


catd) concatenate and 

print 


lpd(VIII) line 

printer daemon 


lpdV) line 

printer 


lprd) spool for line 

printer 

) 


printfdll) formatted print 

oprfl) off line 

print 


printfdll) formatted 

print 


niced) run a command at low 

priority 


nicedl) set program 

priority 
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su(VIII) become 

privileged user 


maze(VI) generate a maze 

problem 


boot 

procedures(VIlI) UNIX startup 


initCVIII) 

process control initialization 


setgid(II) set 

process group ID 


ps(I) 

process status 


times(II) get 

process times 


waitOl) wait for 

process to terminate 


setuidfll) set 

process user ID 


exitGD terminate 

process 


fork(II) spawn new 

process 


• kill(I) terminate a 

process 


killQl) send signal to a 

process 


wait(I) await completion of 

process 

• 

hmul(III) high-order 

product 

proftl) display profile data 


profOO display 

profile data 


monitorQlI) prepare execution 

profile 


profiKlI) execution time 

profile 

profilGD execution time profile 


nice(II) set 

program priority 



psd) process status 
ptx(VI) permuted index 


m6(VI) general 

purpose macroprocessor 
putchardll) write character 
putcGU) buffered output 



pwdG) working directory name 
qsortdll) quicker sort 


qsortdll) 

quicker sort 

randdll) random number generator 


rand(III) 

random number generator 


getchardll) 

read character 


cswdD 

read console switches 


read(II) 

read from file 


pcGV) PC-11 paper tape 

reader/punch 
readdO read from file 


opendD open for 

reading or writing 


seekdO move 

read/write pointer 


crefTD make cross 

reference listing 


reloc(VIII) 

relocate object files 


slripd) remove symbols and 

relocation bits 

reloc(VIII) relocate object files 


unlinkdO 

remove directory entry 


rmdirG) 

remove directory 


slripd) 

remove symbols and relocation bits 


rm(I) 

remove (unlink) files 


mvG) move or 

rename a file 


uniqd) report 

repeated lines in a file 


uniqd) 

report repeated lines in a file 
reset(III) execute non-local goto 


restoKVlII) incremental file system 

restore 

restor(VIII) incremental file system restore 


ttyndll) 

return name of current typewriter 


col(VI) filter 

reverse line feeds 

% 
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rk(IV) RK-11/RK03 (or 
rk(IV) 


sqrtQlI) square 
rp(IV) 

nice(I) 

nohup(I) 

man(I) 

azeKVI) 

sfs(VI) structured file 
grep(I) 
man(I) run off 

mailO) 
killdD 
passwd(0 
sttydl) 
setgiddl) 
seluiddl) 
nicedl) 
tabs(VII) 
dated) print and 
stimedD 
getty(VIII) 
sttyd) 

ascii(VII) map of ASCII character 


tmheadeKVII) TM cover 
sa(VIII) 
shiftd) adjust 
shd) 

msh(VIlI) mini 


logind) 
killdD send 

signaldl) catch or ignore 
catsim(VI) phototypesetter 
sindll) 


rewd) rewind tape 
rewind tape 

RF11/RS11 fixed-head disk file 
rf(IV) RF11/RS11 fixed-head disk file 
RK.05) disk 

RK-11/RK03 (or RK05) disk 
rk(IV) RK-11/RK03 (or RK05) disk 
rmdird) remove directory 
rm(I) remove (unlink) files 
rofld) format text 
root function 

RP-11/RP03 moving-head disk 
rp(IV) RP-11/RP03 moving-head disk 
run a command at low priority 
run a command immune to hangups 
run off section of UNIX manual 
satellite predictions 
sa(VIII) Shell accounting 
scanner 

search a file for a pattern 

section of UNIX manual 

seek(II) move read/write pointer 

send mail to another user 

send signal to a process 

set login password 

set mode of typewriter 

set process group ID 

set process user ID 

set program priority 

set tab stops 

set the date 

set time 

set typewriter mode 
set typewriter options 
set 

setfilQlI) specify Fortran file name 
setgid(II) set process group ID 
setuid(II) set process user ID 
sfs(VI) structured file scanner 
sheet 

Shell accounting 
Shell arguments 
shell (command interpreter) 

Shell 

sh(l) shell (command interpreter) 

shift(I) adjust Shell arguments 

sign onto UNIX 

signa’ o a process 

signaldl) catch or ignore signals 

signals 

simulator 

sine and cosine functions 
sin(IIl) sine and cosine functions 
size of an object file 
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spline(VI) interpolate 
sno(VI) 

sort(I) 

qsortQH) quicker 
fork(Il) 


mknodQl) make a directory or a 
mknod(VIII) build 
setfild*’' 

spell(I) find 
tiu(IV) 

npr(VI) print file on 
splitO) 
lpr(I) 
sqrtQlI) 

boot proceduresCVIII) UNIX 

fstatOD get 
gttyQl) get typewriter 
psd) process 
statdl) get file 

sleepdD 
tabs(VII) set tab 

sfs(VI) 


ibm(VI) 

sumd) 

dud) 

sync(VIII) update the 
update(VIII) periodically update the 
syncdl) update 
sleepd) 

cswdl) read console 
stripd) remove 


vs(VII) voice 
vsdV) voice 


sized) size of an object file 

sky(VI) obtain ephemerides 

sleepd) suspend execution for an interval 

sleepdD stop execution for interval 

smooth curve 

Snobol interpreter 

sno(VI) Snobol interpreter 

sort or merge files 

sortd) sort or merge files 

sort 

spawn new process 

speak.m(V) voice synthesizer vocabulary 
speak(VI) word to voice translator 
special file 
special file 

specify Fortran file name 

spelld) find spelling errors 

spelling errors 

Spider interface 

Spider line-printer 

spline(VI) interpolate smooth curve 

split a file into pieces 

splitd) split a file into pieces 

spool for line printer 

sqrtdll) square root function 

square root function 

startup 

statdl) get file status 

status of open file 

status 

status 

status 

stimedl) set time 

stop execution for inlerval 

stops 

stripd) remove symbols and relocation bits 

structured file scanner 

sttyd) set typewriter options 

sttydD set mode of typewriter 

submit off-line job to HO IBM 370 

sum file 

sumd) sum file 

summarize disk usage 

super block 

super block 

super-block 

suspend execution for an interval 
su(VIII) become privileged user 
switches 

symbols and relocation bits 
syncdl) update super-block 
sync(VIII) update the super block 
synthesizer code 
synthesizer interface 
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speak. m(V) voice synthesizer vocabulary 
indirOl) indirect system call 
introfll) introduction to system calls 

check(VIIl) file system consistency check 
dump(VIII) incremental file system dump 

perroKlII) system error messages 
restor(VIII) incremental file system restore 
mtab(V) mounted file system table 
fs(V) format of file system volume 
20boot(VIII) install new 1 1/20 system 
mkfs(VIII) construct a file system 
mount(II) mount file system 
mount(VIII) mount file system 
umountOl) dismount file system 
umount(VIII) dismount file system 
who(I) who is on the system 
tabs(VII) set tab stops 
mtab(V) mounted file system table 

tabs(VII) set tab stops 
atandll) arc tangent function 
dump(V) incremental dump tape format 
tp(V) DEC/mag tape formats 
pcGV) PC-11 paper tape reader/punch 
rewQ) rewind tape 

tc(IV) TC-11/TU56 DECtape 

tcOV) TC-11/TU56 DECtape 
* teeffi pipe fitting 

grauvl) draw graph on GSI terminal 
gsi(VI) interpret funny characters on GSI terminal 
neqnd) typeset mathematics on terminal 
plog(VI) make a graph on the gsi terminal 

killd) terminate a process 
exitd) terminate command file 
exitdl) terminate process 
waitdl) wait for process to terminate 
edd) text editor 

nroffO) format text * 

rofid) format text 
troffd) format text 

cubic(VI) three dimensional tic-tac-toe 
cubtc(VI) three dimensional tic-tac-toe 
ttt(VI) the game of tic-tac-toe 

timed) time a command 
profildl) execution time profile 
ctimedll) convert date and time to ASCII 

timed) time a command 
timedl) get date and time 
timesdl) get process times 
stimedl) set time 
timesdl) get process times 

timedl) get date and time ) 

tiudV) Spider interface 
tmheader(VII) TM cover sheet 

tmdV) TM-ll/TU-10 magtape interface 


xxviii 



goto(I) command 
speak(VI) word to voice 

trO) 


greek(VII) graphics for extended 


cmp(I) compare 
commd) print lines common to 
greek(VII) graphics for extended TTY-37 

neqn(I) 
eqn(I) 
ttys(V) 
tty(IV) general 
getty(VIII) set 
ttyO) get 
* stty(I) set 

gtty(II) get 
stty(II) set mode of 
ttynQlI) return name of current 

typoO) find possible 
getpw(III) get name from 


mand) run off section of 
boot proceduresCVIII) 
logind) sign onto 
rmd) remove 

syncdl) 
sync(VIII) 
update(VIII) periodically 

dud) summarize disk 
getuiddD get 
setuiddD set process 
utmp(V) 
wtmp(V) 

maild) send mail to another 
su(VIII) become privileged 
wrilefl) write to another 


tmg(VI) compiler-compiler 

tmheader(VIl) TM cover sheet 

tmdV) TM-ll/TU-10 magtape interface 

tpd) manipulate DECtape and magtape 

tp(V) DEC/mag tape formats 

transfer 

translator 

transliterate 

tKD transliterate 

troffd) format text 

tss(I) interface to MH-TSS 

ttt(Vl) the game of tic-tac-toe 

TTY-37 type-box 

ttyd) get typewriter name 

ttydV) general typewriter interface 

ttyndll) return name of current typewriter 

ttys(V) typewriter initialization data 

two files 

two files 

type-box 

typeset mathematics on terminal 

typeset mathematics 

typewriter initialization data 

typewriter interface 

typewriter mode 

typewriter name 

typewriter options 

typewriter status 

typewriter 

typewriter 

typod) find possible typos 

typos 

UID 

umountdD dismount file system 

umount(VIII) dismount file system 

uniqd) report repeated lines in a file 

UNIX manual 

UNIX startup 

UNIX 

(unlink) files 

unlink(II) remove directory entry 
update super-block 
update the super block 
update the super block 

update(VIJI) periodically update the super block 
usage 

user identifications 
user ID 

user information 
user login history 


utmp(V) user information 
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wed) 
speak(VI) 
hyphen(VI) find hyphenated 
pwd(I) 
chdirO) change 
chdirOI) change 
putchaKlII) 
writeQl) 
write© 


opendD open for reading or 


yacc(VI) 


vocabulary 

voice synthesizer code 
voice synthesizer interface 
voice synthesizer vocabulary 
voice translator 
volume 

vsdV) voice synthesizer interface 
vs(V!I) voice synthesizer code 
(vtOl) interface 
(vtOl) interface 
vtdll) display (vtOl) interface 
vtdV) 11/20 (vtOl) interface 
wait for process to terminate 
waitd) await completion of process 
waitdD wait for process to terminate 
wpd) word count 
who is on the system 
who(I) who is on the system 
word count 

word to voice translator 
words 

working directory name 
working directory 
working directory 
write character 
write on a file 
write to another user 
writed) write to another user 
writedl) write on a file 
writing 

wtmp(V) user login history 
wump(VI) the game of hunt-the-wumpus 
yacc(VI) yet another compiler-compiler 
yet another compiler-compiler 
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NAME 

ar — archive and library maintainer 
SYNOPSIS 

ar key afile name ... 

DESCRIPTION 

Ar maintains groups of files combined into a single archive file. Its main use is to create and up- 
date library files as used by the loader. It can be used, though, for any similar purpose. 

Key is one character from the set drtux, optionally concatenated with v. Afile is the archive file. 
The names are constituent files in the archive file. The meanings of the key characters are: 

d means delete the named files from the archive file. 

r means replace the named files in the archive file. If the archive file does not exist, r will -create 
it. If the named files are not in the archive file, they are appended. 

t prints a table of contents of the archive file. If no names are given, all files in the archive are 
tabled. If names are given, only those files are tabled. 

u is similar to r except that only those files that have been modified are replaced. If no names 
are given, all files in the archive that have been modified will be replaced by the modified ver- 
sion. 

x will extract the named files. If no names are given, all files in the archive are extracted. In 
neither case does x alter the archive file. 

v means verbose. Under the verbose option, ar gives a file-by-file description of the making of a 
new archive file from the old archive and the constituent files. The following abbreviations are 
used: 

c copy 
a append 
d delete 
r replace 
x extract 

FILES 

/tmp/vtm? temporary 

SEE ALSO 

Id (I), archive (V) 

BUGS 

Option tv should be implemented as a table with more information. 

There should be a way to specify the placement of a new file in an archive. Currently, it is 
placed at the end. 

Since ar has not been rewritten to deal properly with the new file system modes, extracted files 
have mode 666. 

For the same reason, names are only maintained to 8 characters. 
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NAME 

as — assembler 

SYNOPSIS 

as [ — ] name ... 

DESCRIPTION 

As assembles the concatenation of the named files. If the optional first argument — is used, all 
undefined symbols in the assembly are treated as global. 

The output of the assembly is left on the file a.out. It is executable if no errors occurred during 
the assembly, and if there were no unresolved external references. 

FILES 

/etc/as2 pass 2 of the assembler 

/tmp/atm[l-4]? temporary 
a.out object 

SEE ALSO 

ld(I), nm(I), db(I), a.out(V), ‘UNIX Assembler Manual’. 

DIAGNOSTICS 

When an input file cannot be read, its name followed by a question mark is typed and assembly 
ceases. When syntactic or semantic errors occur, a single-character diagnostic is typed out to- 
gether with the line number and the file name in which it occurred. Errors in pass 1 cause can- 
cellation of pass 2. The possible errors are: 

) Parentheses error 

] Parentheses error 

< String not terminated properly 

* Indirection used illegally 

. Illegal assignment to V 

A Error in address 

B Branch instruction is odd or too remote 

E Error in expression 

F Error in local (T or ‘b’) type symbol 
G Garbage (unknown) character . 

I End of file inside an if 

M Multiply defined symbol as label 

O Word quantity assembled at odd address 

P V different in pass I and 2 

R Relocation error 

U Undefined symbol 

X Syntax error 


BUGS 

Symbol table overflow is not checked, x errors can cause incorrect line numbers in following di- 
agnostics. 
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CAT (I) 


NAME 

cat — concatenate and print 

SYNOPSIS 

cat file ... 

DESCRIPTION 

Cat reads each file in sequence and writes it on the standard output. Thus: 
cat file 

is about the easiest way to print a file. Also: 
cat filel file2 >file3 

is about the easiest way to concatenate files. 

If no input file is given cat reads from the standard input file. 

If the argument — is encountered, cat reads from the standard input file. 

SEE ALSO 

pr(I), cpG) 

DIAGNOSTICS 

none; if a file cannot be found it is ignored. 

BUGS 

cat x y >x and cat x y >y cause strange results. 



CC(I) 


5 / 15/74 
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NAME 

cc — C compiler 
SYNOPSIS 

cc [ — c ] [ — p ] [ — O ] [ — S ] [ — P ] file ... 


DESCRIPTION 

Cc is the UNIX C compiler. It accepts three types of arguments: 

Arguments whose names end with ‘.c’ are taken to be C source programs; they are compiled, and 
each object program is left on the file whose name is that of the source with ‘.o’ substituted for 
‘.c\ The ‘.o’ file is normally deleted, however, if a single C program is compiled and loaded all at 
one go. 

The following flags are interpreted by cc. See Id (I) for load-time flags. 

— c Suppress the loading phase of the compilation, and force an object file to be produced 
even if only one program is compiled. 

— p Arrange for the compiler to produce code which counts the number of times each routine 
is called; also, if loading takes place, replace the standard startup routine by one which au- 
tomatically calls the monitor subroutine (III) at the start and arranges to write out a mon.out 
file at normal termination of execution of the object program. An execution profile can 
then be generated by use of prof (I). 

— O Invoke the experimental object-code optimizer. 

— S Compile the named C programs, and leave the assembler-language output on correspond- 
ing files suffixed ‘.s’. 

— P Run only the macro preprocessor on the named C programs, and leave the output on 
corresponding files suffixed ‘.i\ 

Other arguments are taken to be either loader flag arguments, or C-compatible object programs, 
typically produced by an earlier cc run, or perhaps libraries of C-compatible routines. These pro- 
grams, together with the results of any compilations specified, are loaded (in the order given) to 
produce an executable program witn name a.out. 


FILES 

file.c 

file.o 

a.out 

/tmp/ctm? 

/Iib/ct01] 

/lib/c2 

/lib/crtO.o 

/lib/mcrtO.o 

'/lib/libc.a 

/lib/liba.a 


input file 
object file 
loaded output 
temporary 
compiler 

optional optimizer 
runtime startoff 
runtime startoff for monitoring, 
builtin functions, etc. 
system library 


SEE ALSO 

“Programming in C— a tutorial,” C Reference Manual, monitor (III), prof (I), cdb (I), Id (I). 


DIAGNOSTICS 

The diagnostics produced by C itself are intended to be self-explanatory. Occasional messages 
may be produced by the assembler or loader. Of these, the most mystifying are from the assem- 
bler, in particular “m,” which means a multiply-defined external symbol (function or data). 


BUGS 
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NAME 

cdb — C debugger 
SYNOPSIS 

cdb [ core [ a.out ] ] 

DESCRIPTION 

Cdb is a debugger for use with C programs. The first argument is a core-image file; if not given, 
“core” is used. The second argument is the object program (containing a symbol table); if not 
given “a.out” is used. An acceptable core and object file must both be present. 

Commands to cdb consist of an address followed by a single command character. If no address 
is given the last-printed address is used. An address may be followed by a comma and a 
number, in which case the command applies to the appropriate number of successive addresses. 

Addresses are expressions composed of names, decimal numbers, and octal numbers (which be- 
gin with “0”) and separated by “+” and Evaluation proceeds left-to-right. The construction 
“name[expressionl” assumes that name is a pointer to an integer and is equivalent to the contents 
of the named cell plus twice the expression. 

The command characters are: 

/ print the addressed words in octal. 

= print the value of the addressed expression. 

print the addressed bytes as characters. 

" take the address as a pointer to a sequence of characters, and print the characters up to a 
null byte. 

& If there is any symbol which has the same value as the address, print the symbol’s name. 

$ print a stack trace of the terminated program. The calls are listed in the order made; the ac- 
tual arguments to each routine are given in octal. 


SEE ALSO 

cc (I), db (I), C Reference Manual 


BUGS 

It’s still very feeble, even compared with db (I). The stack trace is also pretty vulnerable to corr- 
uption, and often doesn’t work. 
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CHDIR(I) 


NAME 

chdir — change working directory 

SYNOPSIS 

chdir directory 


DESCRIPTION 

Directory becomes the new working directory. The process must have execute (search) permis- 
sion in directory. 

Because a new process is created to execute each command, chdir would be ineffective if it were 
written as a normal command. It is therefore recognized and executed by the Shell. 

SEE ALSO . 

sh(I) 

BUGS 
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NAME 

chmod — change mode 

SYNOPSIS 

chmod octal file ... 

DESCRIPTION 

The octal mode replaces the mode of each of the files. The mode is constructed from the OR of 
the following modes: 

4000 set user ID on execution 
2000 set group ID on execution 
0400 read by owner 
0200 write by owner 

0100 execute (search in directory) by owner 
0070 read, write, execute (search) by group 
0007 read, write, execute (search) by others 

Only the owner of a file (or the super-user) may change its mode. 

SEE ALSO 

lsd) 


BUGS 
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NAME 

chown — change owner 


SYNOPSIS 

chown owner file ... 


DESCRIPTION 

Owner becomes the new owner of the files. The owner may be either a decimal UID or a login 
name found in the password file. 


Only the owner of a file (or the super-user) is allowed to change the owner. Unless it is done by 
the super-user, the sel-user-ID permission bit is turned off as the owner of a file is changed. 

FILES 

/etc/passwd 


BUGS 
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NAME 

cmp — compare two files 

SYNOPSIS 

cmp filel file2 

DESCRIPTION 

The two files are compared for identical contents. Discrepancies are noted by giving the offset 
and the differing words, all in octal. 

SEE ALSO 

diff (I), comm G) 

BUGS 

If the shorter of the two files is of odd length, cmp acts as if a null byte had been appended to it. 
The offset is only a single-precision number. 
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NAME 

comm — print lines common to two files 
SYNOPSIS 

comm [ — [ 123 ] ] filel file2 

DESCRIPTION 

Comm reads filel and file2, which should be in sort, and produces a three column output: lines 
only in filel; lines only in file2; and lines in both files. 

The output is written on the standard output. 

Flags 1, 2, or 3 suppress printing of the corresponding column. Thus comm —12 prints only the 
lines common to the two files; comm —23 prints only lines in the first file bui not in the second; 
comm —123 is a no-op. 

SEE ALSO 

cmp (1), diff (I) 

BUGS 
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NAME 

cp — copy 

. SYNOPSIS 

cp [ — t ] filel file2 

DESCRIPTION 

The first file is copied onto the second. The mode and owner of the target file are preserved if it 
already existed; the mode of the source file is used otherwise. 

If file2 is a directory, then the target file is a file in that directory with the file-name of filel. 

No one is quite sure what the flag — t does. 

SEE ALSO • 

cat G), pr G), mv G) 

BUGS 

Copying a file onto itself destroys its contents. 
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NAME 

cref — make cross reference listing 


SYNOPSIS 

cref [ — acilostuxl23 ] name ... 


DESCRIPTION 

Cref makes a cross reference listing of program 
as arguments in the command line are searched 


files in assembler or C formal. The files named 
for symbols in the appropriate syntax. 


The output report is in four columns: 

(1) (2) (3) (4) 

symbol file • see text as it appears in file 

below 


Cref uses either an ignore file or an only file. If the — i option is given, it will take the next avail- 
able argument to be an ignore file name; if. the — o option is given, the. next available argument 
will be taken as an only file name. Ignore and only files should be lists of symbols separated by 
new lines. If an ignore file is given, all the symbols in that file will be ignored in columns (1) and 
(3) of the output. If an only file is given, only symbols appearing in that file will appear in 
column (1). Only one of the options -i or -o may be used. The default setting is -i. Assem- 
bler predefined symbols or C keywords are ignored. 

The — s option causes current symbols to be put in column 3. In the assembler, the current sym- 
bol is the most recent name symbol; in C, the current function name. The -I option causes the 
line number within the file to be put in column 3. 

The — t option causes the next available argument to be used as the name of the intermediate 
temporary file (instead of /imp/cri??). The file is created and is not removed at the end of the 
process. 

Options: 

a assembler formal (default) 
c C format input 
i use ignore file (see above) 

I put. line number in col. 3 (instead of current symbol) 

0 use only file (see above) 

s current symbol in col. 3 (default) 
t user supplied temporary file 
u print only symbols that occur exactly once 
x print only C external symbols 

1 sort output on column 1 (default) 

2 sort output on column 2 

3 sort output on column 3 


FILES 

/tmp/crt?? 

/usr/lib/aign 

/usr/lib/cign 

/usr/bin/crpost 

/usr/bin/uposi 

/bin/sort 


temporaries 

default assembler ignore file 
default C ignore file 
post processor 

post processor for — u option 
used to sort temporaries 


SEE ALSO 

as (1), cc (1) 


BUGS 
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NAME 

date — print and set the date 
SYNOPSIS 

date [ mmddhhmm[yy] ] 

DESCRIPTION 

If no argument is given, the current date is printed to the second. If an argument is given, the 
current date is set. The first mm is the month number; dd is the day number in the month; hh is 
the hour number (24 hour system); the second mm is the minute number; yy is the last 2 digits of 
the year number and is optional. For example: 

date 10080045 

sets the' date to Oct 8, 12:45 AM. The current year is the default if no year is mentioned. The 
system operates in GMT. Date takes care of the conversion to and from local standard and day- 
light time. 

DIAGNOSTICS 

‘bad conversion’ if the argument is syntactically incorrect. 

BUGS 
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NAME 

db — debug 
SYNOPSIS 

db [ core [ namelist ] ] [ — ] 

DESCRIPTION 

Unlike many debugging packages (including DEC's ODT, on which db is loosely based), db is not 
loaded as part of the core image which it is used to examine; instead it examines files. Typically, 
the file yvill be either a core image produced after a fault or the binary output of the assembler. 
Core is the file being debugged; if omitted core is assumed. Namelist is a file containing a symbol 
table. If it is omitted, the symbol table is obtained from the file being debugged, or if not there 
from a.out. If no appropriate name list file can be found, db can still be used but some of its 
symbolic facilities become unavailable. 

For the meaning of the optional third argument, see the last paragraph below. 

The format for most db requests is an addres.s followed by a one character command. Addresses 
are expressions built up as follows: 

1. A name has the value assigned to it when the input file was assembled. It may be relocat- 
able or not depending on the use of the name during the assembly. 

2. An octal number is an absolute quantity with the appropriate value. 

3. A decimal number immediately followed by V is an absolute quantity with the appropriate 
value. 

4. An octal number immediately followed by r is a relocatable quantity with the appropriate 
value. 

5. The symbol . indicates the current pointer of db. The current pointer is set by many db re- 
quests. 

6. A * before an expression forms an expression whose value is the number in the word ad- 
dressed by the first expression. A * alone is equivalent to ‘V. 

7. Expressions separated by + or blank are expressions with value equal to the sum of the 
components. At most one of the components may be relocatable. 

8. Expressions separated by — form an expression with value equal to the difference to the 
components. If the right component is relocatable, the left component must be relocatable. 

9. Expressions are evaluated left to right. 

Names for registers are built in: 

r0 ... r5 

sp 

pc 

frO ... fr5 

These may be examined. Their values are deduced from the contents of the stack in a core im- 
age file. They are meaningless in a file that is not a core image. 

If no address is given for a command, the current address (also specified by “.”) is assumed. In 
general, points to the last word or byte printed by db. 

There are db commands for examining locations interpreted as numbers, machine instructions, 
ASCII characters, and addresses. For numbers and characters, either bytes or words may be ex- 
amined. The following commands are used to examine the specified file. 

/ The addressed word is printed in octal. 

\ The addressed byte is printed in octal. 
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" The addressed word is primed as two ASCII characters. 

The addressed byte is printed as an ASCII character. 

The addressed word is printed in decimal. 

? The addressed word is interpreted as a machine instruction and a symbolic form of the in- 
struction, including symbolic addresses, is printed. Often, the result will appear exactly as it 
was written in the source program. 

& The addressed word is interpreted as a symbolic address and is printed as the name of the 
symbol whose value is closest to the addressed word, possibly followed by a signed offset. 

<nl>(i. e., the character “new line”) This command advances the current location counter 
and prints the resulting location in the mode last specified by one of the above requests. 

This character decrements and prints the resulting location in the mode last selected one 
of the above requests. It is a converse to <nl>. 

% Exit. 

Odd addresses to word-oriented commands are rounded down. The incrementing and decre- 
menting of done by the <nl> and ' requests is by one or two depending on whether the last 
command was word or byte oriented. 

The address portion of any of the above commands may be followed by a comma and then by 
an expression. In this case that number of sequential words or bytes specified by the expression 
is printed. is advanced so that it points at the last thing printed. 

There are two commands to interpret the value of expressions. 

= When preceded by an expression, the value of the expression is typed in octal. When not 
preceded by an ‘expression, the value of is indicated. This command does not change the 
value of 

: An attempt is made to print the given expression as a symbolic address. If the expression is 
relocatable, that symbol is found whose value is nearest that of the expression, and the sym- 
bol is typed, followed by a sign and the appropriate offset. If the value of the expression is 
absolute, a symbol with exactly the indicated value is sought and printed if found; if no 
matching symbol is discovered, the octal value of the expression is given. 

The following command may be used to patch the file being debugged. 

! This command must be preceded by an expression. The value of the expression is stored at 
the location addressed by the current value of The opcodes do not appear in the sym- 
bol table, so the user must assemble them by hand. 

The following command is used after a fault has caused a core image file to be produced. 

$ causes the fault type and the contents of the general registers and several other registers to 
be printed both in octal and symbolic format. The values are as they were at the time of the 
fault. 

For some purposes, it is important to know how addresses typed by the user correspond with lo- 
cations in the file being debugged. The mapping algorithm employed by db is non-lrivial for two 
reasons: First, in an a. out file, there is a 20(8) byte header which will not appear when the file is 
loaded into core for execution. Therefore, apparent location 0 should correspond with actual file 
offset 20. Second, addresses in core images do not correspond with the addresses used by the 
program because in a core image there is a header containing the system’s per-process data for 
the dumped process, and also because the stack is stored contiguously with the text and data part 
of the core image rather than at the highest possible locations. Db obeys the following rules: 

If exactly one argument is given, and if it appears to be an a.out file, the 20-byte header is 
skipped during addressing, i.e., 20 is added to all addresses typed. As a consequence, the header 
can be examined beginning at location —20. 
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If exactly one argument is given and if the file does not appear to be an a. out file, no mapping is 
done. 

If zero or two arguments are given, the mapping appropriate to a core image file is employed. 
This means that locations above the program break and below the stack effectively do not exist 
(and are not, in fact, recorded in the core file). Locations above the user’s stack pointer are 
mapped, in looking at the core file, to the place where they are really stored. The per-process da- 
ta kept by the system, which is stored in the first part of the core file, cannot currently be exam- 
ined (except by $). 

If one wants to examine a file which has an associated name list, but is not a core image file, the 
last argument ” can be used (actually the only purpose of the last argument is to make the 
number of arguments not equal to two). This feature is used most frequently in examining the 
memory file /dev/mem. 

SEE ALSO 

as (I), core (V), a.out (V), od (I) 

DIAGNOSTICS 

“File not found” if the first argument cannot be read; otherwise 

BUGS 

There should be some way to examine the registers and other per-process data in a core image; 
also there should be some way of specifying double-precision addresses. It does not know yet 
about shared text segments. 
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NAME 

dc — desk calculator 

SYNOPSIS 

dc [ file ] 


DESCRIPTION 

Dc is an arbitrary precision integer arithmetic package. The overall structure of dc is a stacking 
(reverse Polish) calculator. The following constructions are recognized by the calculator: 

number The value of the number is pushed on the stack. A number is an unbroken string of 
the digits 0-9. It may be preceded by an underscore _ to input a negative number. 

+ 



% 

* The top two values on the stack are added (+), subtracted (— ), multiplied (*), divided 

(/), remaindered (%), or exponentiated O. The two entries are popped off the stack; 
the result is pushed on the stack in their place. 

sx The top of the stack is popped and stored into a register named x, where x may be 

any character. 

lx The value in register x is pushed on the stack. The register x is not altered. All re- 

gisters start with zero value. 

d The top value on the stack is duplicated. 

p The top value on the stack is printed. The top value remains unchanged, 

f All values on the stack and in registers are printed. 

q exits the program. If executing a string, the recursion level is popped by two. 

x treats the top element of the stack as a character string and executes it as a string of 

dc commands. 

I ... 1 puts the bracketed ascii string onto the top of the stack. 

<x 

=x 

>x The top two elements of the stack are popped and compared. Register x is executed 

if they obey the stated relation. 

v replaces the top element on the stack by its square root. 

! interprets the rest of the line as a UNIX command, 

c All values on the stack are popped. 

i The top value on the stack is popped and used as the number radix for further input. 

o The top value on the stack is popped and used as the number radix for further out- 

put. 

z The stack level is pushed onto the stack. 

? A line of input is taken from the input source (usually the console) and executed. 

new-line ignored except as the name of a register or to end the response to a ?. 

space ignored except as the name of a register or to terminate a number. 

If a file name is given, input is taken from that file until end-of-file, then input is taken from the 
console. An example which prints the first ten values of n! is 

l lal+dsa*plalO > xlsx 

Osal 

lxx 
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FILES 

/etc/msh lo implement T 


DIAGNOSTICS 

(x) ? for unrecognized character x. 

(x) ? for not enough elements on the slack to do what was asked by command x. 
‘Out of space’ when the free list is exhausted (too many digits). 

‘Out of headers’ for loo many numbers being kept around. 

‘Out of pushdown’ for loo many items on the stack. 

‘Nesting Depth’ for too many levels of nested execution. 


BUGS 


% 
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NAME 

dd — convert and copy a file 
SYNOPSIS 

dd [option=value] ... 

DESCRIPTION 

Dd copies its specified input file to its specified output with possible conversions. The input and 
output block size may be specified to take advantage of raw physical I/O. 


option 

values 

if= 

input file name; standard input is default 

of= 

output file name; standard output is default 

ibs= 

input block size (default 512) 

obs= 

output block size (default 512) 

bs= 

set both input and output block size, superseding ibs and obs; also, if no conver- 
sion is specified, it is particularly efficient since no copy need be done 

cbs=n 

conversion buffer size 

skip=« 

skip n input records before starting copy 

count=rt 

copy only n input records 

conv=ascii 

convert EBCDIC to ASCII 

ebcdic 

convert ASCII to EBCDIC 

lease 

map alphabetics to lower case 

ucase 

map alphabetics to upper case 

swab • 

swap every pair of bytes 

noerror 

do not stop processing on an error 

sync 

pad every input record to ibs 

... , ... 

several comma-separated conversions 


Where sizes are specified, a number of bytes is expected. A number may end with k, b or w to 
specify multiplication by 1024, 512, or 2 respectively. Also a pair of numbers may be separated 
by x to indicate a product. 

Cbs is used only if ascii or ebcdic conversion is specified. In the former case cbs characters are 
placed into the conversion buffer, converted to ASCII, and trailing blanks trimmed and new-line 
added before sending the line to the output. In the latter case ASCII characters are read into the 
conversion buffer, converted to EBCDIC, and blanks added to make up an output record of size 
cbs. 

After completion, dd reports the number of whole and partial input and output blocks. 

For example, to read an EBCDIC tape blocked ten 80-byte EBCDIC card images per record into 
the ASCII file x: 

dd if=/dev/rmtO of=x ibs=800 cbs=80 conv=ascii, lease 

Note the use of raw magtape. Dd is quite suited to I/O on the raw physical devices because it al- 
lows reading and writing in arbitrary record sizes. 

SEE ALSO 

cp 0) 

BUGS 

The ASCII/EBCDIC conversion tables are taken from the 256 character standard in the CACM 
Nov, 1968. It is not clear how this relates to real life. 
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NAME 

difT — differential file comparator 
SYNOPSIS 

diff [ — ] namel name2 
DESCRIPTION 

Diff tells what lines must be changed in two files to bring them into agreement. The normal out- 
put contains lines of these forms: 

nl a n3,n4 
nl,n2 d n3 
nl,n2 c n3,n4 

These lines resemble ed commands to convert file namel into file namc2. The numbers after the 
letters pertain to file name2. In fact, by exchanging ‘a’ for ‘d’ and reading backward one may 
ascertain equally how to convert file name2 into namel. As in ed, identical pairs where nl = n2 
or n3 = n4 are abbreviated as a single number. 

Following each of these lines come all the lines that are affected in the first file flagged by 
then all the lines that are affected in the second file flagged by V. 

Under the — option, the output of diff is a script of a, c and d commands for the editor ed, which 
will change the contents of the first file into the contents of the second. In this connection, the 
following shell program may help maintain multiple versions of a file. Only an ancestral file (SI) 
and a chain of version-to-version ed scripts (S2,$3,...) made by diff need be on hand, A ‘latest 
version’ appears on the standard output. 

(cat $2 ... $9; echo ’T,Sp”) | ed — SI 

Diff does an optimal and*unfailing job of detecting the file differences, and also reports these 
differences side-by-side. However, diff uses a quadratic algorithm that usually slows to a crawl on 
2000-line flies. 

SEE ALSO 

cmp (I), comm (I), ed (I) 

DIAGNOSTICS 

‘can’t open input’ 

‘arg count’ 

‘jackpot’ — To speed things up, the program uses hashing. You have stumbled on a case where 
there is a minuscule chance that this has resulted in an unnecessarily long list of differences be- 
ing published. It’s a curio that we’d like to see. 


BUGS 

Editing scripts produced under the — option are naive about creating lines consisting of a single 

i * 
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NAME 

dsw — delete interactively 

SYNOPSIS 

dsw [ directory ] 

DESCRIPTION 

For each file in the given directory (V if not specified) dsw types its name. If y is typed, the file 
is deleted; if x, dsw exits; if new-line, the file is not deleted; if anything else, dsw asks again. 

SEE ALSO 

rmco 

BUGS 

The name dsw is a carryover from the ancient past. Its etymology is amusing. 
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NAME 

du — summarize disk usage 


SYNOPSIS 

du [ — s ] [ — a ] [ name ... ] 


DESCRIPTION 

Du gives the number of blocks contained in all files and (recursively) directories within each 
specified directory or file name. If name is missing, V is used. 

The optional argument — s causes only the grand total to be given. The optional argument —a 
causes an entr/ to be generated for each file. Absence of either causes an entry to be generated 
for each directory only. 

A file which has two links to it is only counted once. 


BUGS 

Non-directories given as arguments (not under —a option) are not listed. 

Removable file systems do not work correctly since i-numbers may be repeated while the 
corresponding files are distinct. Du should maintain an i-number list per root directory encoun- 
tered. 
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NAME 

echo — echo arguments 

SYNOPSIS 

echo [ arg ... 1 

DESCRIPTION 

Echo writes all its arguments in order as a line on the standard output file. It is mainly useful for 
producing diagnostics in command files. 


BUGS 
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NAME 

ed — text editor 

SYNOPSIS 

ed [ — ] [ name ] 

DESCRIPTION 

Ed is the standard text editor. 

If a name argument is given, erf simulates an e command (see below) on the named file; that is to 
say, the file is read into ed's buffer so that it can be edited. The optional — simulates an os com- 
mand (see below) which suppresses the printing of character counts by e, r, and w commands. 

Ed operates on a copy of any file it is editing; changes made in the copy have no effect on the file 
until a w (write) command is given. The copy of the text being edited resides in a temporary fjle 
called the buffer. There is only one buffer. 

Commands to ed have a simple and regular structure: zero or more addresses followed by a single 
character command, possibly followed by parameters to the command. These addresses specify 
one or more lines in the buffer. Every command which requires addresses has default addresses, 
so that the addresses can often be omitted. 

In general, only one command may appear on a line. Certain commands allow the input of text. 
This text is placed in the appropriate place in the buffer. While ed is accepting text, it is said to 
be in inpul mode. In this mode, no commands are recognized; all input is merely collected. Input 
mode is left by typing a period V alone at the beginning of a line. 

Ed supports a limi.ted form of regular expression notation. A regular expression is an expression 
which specifies a set of strings of characters. A member of this set of strings is said to be 
matched by the regular expression. The regular expressions allowed by ed are constructed as 
follows: 

1. An ordinary character (not one of those discussed below) is a regular expression and 
matches that character. 

2. A circumflex at the beginning of a regular expression matches the null character at the 
beginning of a line. 

3. A currency symbol k $’ at the end of a regular expression matches the null character at the 
end of a line. 

4. A period V matches any character but a new-line character. 

5. A regular expression followed by an asterisk matches any number of adjacent oc- 
currences (including zero) of the regular expression it follows. 

6. A string of characters enclosed in square brackets ‘[ ]’ matches any character in the string 
but no others. If, however, the first character of the siring is a circumflex the regular 
expression matches any character but new-line and the characters in the string. 

7. The concatenation of regular expressions is a regular expression which matches the con- 
catenation of the strings matched by the components of the regular expression. 

8. The null regular expression standing alone is equivalent to the last regular expression en- 
countered. 

Regular expressions are used in addresses to specify lines and in one command (see s below) to 
specify a portion of a line which is to be replaced. 

If it is desired to use one of the regular expression metacharacters as an ordinary character, that 
character may be preceded by ‘\\ This also applies to the character bounding the regular expres- 
sion (often V') and to ‘V itself. 

Addresses are constructed as follows. To understand addressing in ed it is necessary to know 
that at any time there is a current line. Generally speaking, the current line is the last line 
affected by a command; however, the exact effect on the current line by each command is dis- 
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cussed under the description of the command. 

1. The character V addresses the current line. . 

2. The character ‘ A ’ addresses the line immediately before the current line. 

3. The character T addresses the last line of the buffer. 

4. A decimal number n addresses the n- th line of the buffer. 

5. ‘V addresses the line associated (marked) with the mark name character x which must be 
a printable character. Lines are marked with the k command described below. 

6. A regular expression enclosed in slashes 7’ addresses the first line found by searching to- 
ward the end of the buffer and stopping at the first line containing a string matching the 
regular expression. If necessary the search wraps around to the beginning of the buffer. 

7. A regular expression enclosed in queries 'V addresses the first line found by searching to- 
ward the beginning of the buffer and stopping at the first line found containing a string 
matching the regular expression. If necessary the search wraps around to the end of the 
buffer. 

8. An address followed by a plus sign *+’ or a minus sign ’ followed by a decimal number 
specifies that address plus (resp. minus) the indicated number of jines. The plus sign may 
be omitted. 

Commands may require zero, one, or two addresses. Commands which require no addresses re- 
gard the presence of an address as an error. Commands which accept one or two addresses as- 
sume default addresses when insufficient are given. If more addresses are given than such a 
command requires, the last one or two (depending on what is accepted) are used. 

Addresses are separated from each other typically by a comma ‘,\ They may also be separated 
by a semicolon ‘;\ In this case the current line V is set to the previous address before the next 
address is interpreted. This feature can be used to determine the starting line for forward and 
backward searches C/\ *?’) . The second address of any two-address sequence must correspond to 
a line following the line corresponding to the first address. 

In the following list of ed commands, the default addresses are shown in parentheses. The 
parentheses are not part of the address, but are used to show that the given addresses are the de- 
fault. 

As mentioned, it is generally illegal for more than one command to appear on a line. However, 
any command may be suffixed by ‘p’ (for ‘print’). In that case, the current line is printed after 
the command is complete. 

( . )a 
<text> 

The append command reads the given text and appends it after the addressed line. V 
is left on the last line input, if there were any, otherwise at the addressed line. Ad- 
dress ‘0’ is legal for this command; text is placed at the beginning of the buffer. 

( • > • )c 
<text> 

The change command deletes the addressed lines, then accepts input text which re- 
places these lines. V is left at the last line input; if there were none, it is left at the 
first line not changed. 

(...) d 

The delete command deletes the addressed lines from the buffer. The line originally 
after the last line deleted becomes the current line; if the lines deleted were originally 
at the end, the new last line becomes the current line. 
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e filename 

The edit command causes the entire contents of the buffer to be deleted, and then the 
named file to be read in. V is set to the last line of the buffer. The number of char- 
acters read is typed, ‘filename’ is remembered for possible use as a default file name 
in a subsequent r or w command. 

f filename 

The filename command prints the currently remembered file name. If ‘filename’ is 
given, the currently remembered file name is changed to ‘filename’. 

(l,$)g/regular expression/command list 

In the global command, the first step is to mark every line which matches the given 
regular expression; Then for every such line, the given command list is executed 
with V initially set to that line. A sipgle command or the first of multiple commands 
appears on the same line with the global command. All lines of a multi-line list ex- 
cept the last line must be ended with ‘\\ A, i, and c commands and associated input 
are permitted; the V terminating input mode may be omitted if it would be on the 
last line of the command list. The (global) commands, g, and v, are not permitted in 
the command list. 

( . )i 

<texl> 

This command inserts the given text - before the addressed line. ‘.’ is left at the last 
line input; if there were none, at the addressed line. This command differs from the 
a command only in the placement of the text. 

( . ) kx 

The mark command associates or marks the addressed line with the single character 
mark name x. The ten most recent, mark names are remembered. The current mark 
names may be printed with the n command. 

(.,.)1 

The list command will print the addressed lines in a way that is unambiguous. Non- 
graphic characters are printed in octal, prefixed characters are overstruck with a 
circumflex, and long lines are folded. 

( . , . )ma 

The move command will reposition the addressed lines after the line addressed by a. 
The last of the moved lines becomes the current line. 

n 

The n command will print the current mark names. 

os 

ov 

After os character counts printed by e, r, and w are suppressed. Ov turns them back 
on. 

(.,.)p 

The print command prints the addressed lines. V is left at the last line printed. The 
p command may be placed on the same line after any command. 

q 

The quit command causes ed to exit. No automatic write of a file is done. 

(S) r filename 

The read command reads in the given file after the addressed line. If no file name is 
given, the remembered file name, if any, is used (see e and / commands). The 
remembered file name is not changed unless ‘filename’ is the very first file name 
mentioned. Address ‘0’ is legal for r and causes the file to be read at the beginning of 
the buffer. If the read is successful, the number of characters read is typed. V is left 
at the last line read in from the file; 
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( . , . ) s/regular expression/replacemenl/ or, 

( . , . )s/regular expression/replacement/g 

The substitute command searches each addressed line for an occurrence of the 
specified regular expression. On each line in which a match is found, all matched 
strings are replaced by the replacement specified, if the global replacement indicator 
‘g’ appears after the command. If the global indicator does not appear, only the first 
occurrence of the matched string is replaced. It is an error for the substitution to fail 
on all addressed lines. Any character other than space or new-line may be used in- 
stead of 7’ to delimit the regular expression and the replacement. V is left at the last 
line substituted. 

An ampersand appearing in the replacement is replaced by the regular expression 
that was matched. The special meaning of ‘&’ in this context may be suppressed by 
preceding it by ‘\\ . . 

(l,$)v/regular expression/command list 

This command is the same as the global command except that the command list is 
executed with V initially set to every line except those matching the regular expres- 
sion. 

(l,$)w filename 

The write command writes the addressed lines onto the given file. If the file does not 
exist, it is created mode 666 (readable and writeable by everyone). The remembered 
file name is not changed unless .‘filename’ is the very first file name mentioned. If no 
file name is given, the remembered file name, if any, is used (see e and /commands). 
V is unchanged. If the command is successful, the number of characters written is 
typed. 

($)= 

The line number of the addressed line is typed. V is unchanged by this command. 
IUNIX command 

The remainder of the line after the *!’ is sent to UNIX to be interpreted as a com- 
mand. V is unchanged. The entire shell syntax is not recognized. See msh(VII) for 
the restrictions. 

( .+1 ) <newline> 

An address alone on a line causes the addressed lin'e to be printed. A blank line 
alone is equivalent to ‘.+lp’; it is useful for stepping through text. 

If an interrupt signal (ASCII DEL) is sent, ed will print a ‘?’ and return to its command level. 

If invoked with the command name (see init(VII)) ed will sign on with the message ‘Editing 
system’ and print **’ as the command level prompt character. 

Ed has size limitations on the maximum number of lines that can be edited, on the maximum 
number of characters in a line, in a global’s command list, in a remembered file name, and in the 
size of the temporary file. The current sizes are: 4000 lines per file, 512 characters per line, 256 
characters per global command list, 64 characters per file name, and 64K characters in the tem- 
porary file (see BUGS). 


FILES 

/tmp/etm?, temporary 

/etc/msh, to implement the ‘!’ command. 

DIAGNOSTICS 

*?’ for errors in commands; ‘TMP’ for temporary file overflow. 

SEE ALSO 

A Tutorial Introduction to the ED Text Editor (internal memorandum) 

BUGS 

The temporary file can grow to no more than 64K bytes. 
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NAME 

eqn — typeset mathematics 


SYNOPSIS 

eqn [ file ] ... 


DESCRIPTION 

Eqn is a troff (I) preprocessor for typesetting mathematics on the Graphics Systems photo- 
typesetter. Usage is almost always 

eqn file ... | troff 

If no files are specified, eqn reads from the standard input. A line beginning with “.EQ” marks 
the start of adequation; the end of an equation js marked by a line beginning with “.EN”. Nei- 
ther of these lines is altered or defined by eqn, so you can define them yourself to get centering, 
numbering, etc. All other lines are treated as comments, and passed through untouched. 

Spaces, tabs, newlines, braces, double quotes, tilde and circumflex are the only delimiters. Braces 
“{}” are used for grouping. Use tildes to get extra spaces in an equation. 


Subscripts and superscripts are produced with the keywords sub and sup. Thus x sub i makes x,-, 
a sub i sup 2 produces a}, and e sup {x sup 2 + y sup 2} gives e x + - v . Fractions are made with 

over, a over b is and 1 over sqrt {ax sup 2 -H?x+c) is — , ■ sqrt makes square 

o v ax 2 + bx+ c 


roots. 


The keywords from and to introduce lower and upper limits on arbitrary things: lim£x,- is 

n— oo Q 

made with Urn from { n-> inf) sum from 0 to n x sub i. Left and right brackets, braces, etc., of the 
right height are made with left and right: left [ x sup 2 + y sup 2 over alpha right ] — 1 produces 
2 

x 2 + -^— =1. The right clause is optional. 

a 

Vertical piles of things are made with pile, lpile, cpile, and rpile: pile { a above b above c) pro- 
a 

duces b. There can be an arbitrary number of elements in a pile, lpile left-justifies, pile and 
c 

cpile center, with different vertical spacing, and rpile right justifies. 

Diacritical marks are made with dot, dotdot, hat, bar: x dot =f0) bar is x —fit). Default sizes 
and fonts can be changed with size n and various of roman, italic, and bold. 

Keywords like sum C£) int (J* ) inf (oo) and shorthands like >= (^ ) — > ( *■ ), ! = (^). are 
recognized. Spell out Greek letters in the desired case', as in alpha, GAMMA. Mathematical 
words like sin, cos, log are made Roman automatically. Troff (I) four-character escapes like \(bs 
((§)) can be used anywhere. Strings enclosed in double quotes "..." are passed through untouched. 


SEE ALSO 

A System for Typesetting Mathematics (Computer Science Technical Report #17, Bell Labora- 
tories, 1974.) 

TROFF Users’ Manual (internal memorandum) 

TROFF Made Trivial (internal memorandum) 
troff (I), neqn (I) 

BUGS 

Undoubtedly. Watch out for small or large point sizes — it’s tuned too well for size 10. Be cau- 
tious if inserting horizontal or vertical motions, and of backslashes in general. 
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NAME 

exit — terminate command file 


SYNOPSIS 

exit 


DESCRIPTION 

Exit performs a seek to the end of its standard input file. Thus, if it is invoked inside a file of 
commands, upon return from exit the shell will discover an end-of-file and terminate. 


SEE ALSO 

if (I), goto (I), sh (I) 


BUGS 
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NAME 

fc — foriran compiler 
SYNOPSIS 

fc [ — c ] sfilel.f ... ofilel ... 

DESCRIPTION 

Fc is the UNIX Foriran compiler. It accepts three types of arguments: 

Arguments whose names end with ‘.f are assumed to be Fortran source program units; they are 
compiled, and the object program is left on the file sfilel.o (i.e. the file whose name is that of 
the source with ‘.o’ substituted for \f). 

Other arguments (except for — c) are assumed to be either loader flags, or object programs, typi- 
cally produced by an earlier fc run, or 'perhaps' libraries of Fortran-compatible routines. These 
programs, together with the results of any compilations specified, are loaded (in the order given) 
to produce an executable program with name a. out. 

The — c argument suppresses the loading phase, as does any syntax error in any of the routines 
being compiled. 

The following is a list of differences between fc and ANSI standard Foriran (also see the BUGS 
section): 

1. Arbitrary combination of types is allowed in. expressions. Not all combinations are expected 
to be supported at runtime. All of the normal conversions involving integer, real, double 
precision and complex are allowed. 

2. DEC’S implicit statement is recognized. E.g.: implicit integer /i— n/ 

3. The types doublecomplex, logical*l, integer*l, integer*2 and real*8 (double precision) are 
supported. 

4. & as the first character of a line signals a continuation card. 

5. c as the first character of a line signals a comment. 

6. All keywords are recognized in lower case. ! 

7. The notion of ‘column 7’ is not implemented. 

'8. G-format input is free form— leading blanks are ignored, the first blank after the start of the 
number terminates the field. 

9. A comma in any numeric or logical input field terminates the field. 

10. There is no carriage control on output. 

11. A sequence of n characters in double quotes is equivalent to n h followed by those charac- 
ters. 

12. In data statements, a hollerith string may initialize an array or a sequence of array elements. 

13. The number of storage units requested by a binary read must be identical to the number 
contained in the record being read. 

14. If the first character in an input file is “#”, a preprocessor identical to the C preprocessor is 
called, which implements “#define” and “#include” preprocessor statements. (See the C 
reference manual for details.) The preprocessor does not recognize Hollerith strings written 
with /;h. 

In I/O statements, only unit numbers 0-19 are supported. Unit number n refers to file fortwr; 
(e.g. unit 9 is file ‘fort09’). For input, the file must exist; for output, it will be created. Unit 5 is 
permanently associated with the standard input file; unit 6 with the standard output file. Also 
see setfil (III) for a way to associate unit numbers with named files. 
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FILES 

file.f 

a.out 

f.tmp[123] 

/usr/forl/fcl 

/lib/frO.o 

/lib/filib.a 

/lib/libf.a 

/lib/liba.a 


input file 
loaded output 
temporary (deleted) 
compiler proper 
runtime startofF 
interpreter library 
builtin functions, etc. 
system library 


SEE ALSO 

ANSI standard. Id (I) for loader flags 

Also see the writeups on the precious few non-standard Fortran subroutines, ierror and setfil (III) 
DIAGNOSTICS 

Compile-time diagnostics are given in English, accompanied if possible with the offending line 
number and source line with an underscore where the error occurred. Runtime diagnostics are 
given by number as follows: 

1 invalid log argument 

2 bad arg count to amod 

3 bad arg count to atan2 

4 excessive argument to cabs 

5 exp too large in cexp 

6 bad arg count to cmplx 

7 bad arg count to dim 

8 excessive argument to exp 

9 bad arg count to idim 

10 bad arg count to isign 

11 bad arg count to mod V 

12 bad arg count to sign 

13 illegal argument to sqrt 

14 assigned/computed goto out of range 

15 subscript out of range 

16 real**real overflow 

17 (negative real)** real ' 

100 illegal I/O unit number 

101 inconsistent use of I/O unit 

102 cannot create output file 

103 cannot open input file 

104 EOF on input file 

105 illegal character in format 

106 • format does not begin with ( 

107 no conversion in format but non-empty list 

108 excessive parenthesis depth in format 

109 illegal format specification 

110 illegal character in input field 

111 end of format in hollerith specification 

112 bad argument to setfil 
120 bad argument to ierror 

999 unimplemented input conversion 

Any of these errors can be caught by the program; see ierror (III). 


BUGS 

The following is a list of those features not yet implemented: 
arithmetic statement functions 
scale factors on input 
Backspace statement. 


- 2 - 



FED (I) 


1 / 15/73 
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NAME 

fed — edit associative memory for form letter 

SYNOPSIS 

fed 

DESCRIPTION 

Fed is used to edit a form letter associative memory file, form.m, which consists of named 
strings. Commands consist of single letters followed by a list of string names separated by a sin- 
gle space and ending with a new line. The conventions of the Shell with respect to and '?’ 
hold for all commands but m. The commands are: 

e name ... 

Fed writes the string whose name is name onto a temporary file and executes ed. On exit 
from the ed the temporary file is copied back into the associative memory. Each argument is 
operated on separately. Be sure to give an ed w command (without a filename) to rewrite fed's 
temporary file before quitting out of ed. 

d [ name ... ] 

deletes a string and its name from the memory. When called with no arguments d operates 
in a verbose mode typing each string name and deleting only if a y is typed. A q response re- 
turns to fed s command level. Any other response does nothing. 

m namel name2 ... 

(move) changes the name of namel to name2 and removes previous string name2 if one ex- 
ists. Several pairs of arguments may be given. Literal strings are expected for the names. 

n [ name ... ] 

(names) lists the string names in the memory. If called, with the optional arguments, it just 
lists those requested. * 

p name ... \ 

prints the contents of the strings with names given by the arguments. 

q 

returns to the system, 
c [ p ] [ f ] 

checks the associative memory file for consistency and reports the number of free headers 
and blocks. The optional arguments do the following: 

p causes any unaccounted-for string to be printed. 

f fixes broken memories by adding unaccounted-for headers to free storage and removing 
references to released headers from associative memory. 


FILES 

/tmp/ftmp? temporary 

form.m associative memory 

SEE ALSO 

form(I), ed(I), sh(I) 

WARNING 

It is legal but unwise to have string names with blanks, or *?’ in them. 
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NAME 

find — find files 
SYNOPSIS 

find pathname expression 


DESCRIPTION 

Find recursively descends the directory hierarchy from pathname seeking files that match a 
boolean expression written in the primaries given below. In the descriptions, the argument n is 
used as a decimal integer where +n means more than n, -n means less than n and n means ex- 
actly n. 

—name filename True if the filename argument matches the current file name. Normal Shell 
argument syntax may be used if escaped (watch out for ‘[’, *?’ and “!’). 

-perm onum True if the file permission flags exactly match the octal number onum (see 
chmod(I)). If onum is prefixed by a minus sign, more flag bits (017777, see 
stat(II)) become significant and the flags will be compared: 
(fl ags& on um)==on um. 


—type c 

—links n 
—user uname 
—group gname 
—size n 
— atime n 


True if the type of the file is c, where c is b, c, d or f for block special file, 
character special file, directory or plain file. 

True if the file has n links. 

True if the file belongs to the user uname. 

As it is for —user so shall it be for —group (someday). 

True if the file is n blocks long (512 bytes per block). 

True if the file has been accessed in n days. 


— mtime n True if the file has been modified in n days. 

—exec command True if the executed command returns exit status zero (most commands do). 

The end of the command is punctuated by an escaped semicolon. A com- 
mand argument ‘O' is replaced by the current pathname. 

—ok command Like —exec except that the generated command line is printed with a ques- 
tion mark first, and is executed only if the user responds y. 


—print Always true; causes the current pathname to be printed. 


The primaries may be combined with these operators (ordered by precedence): 


! prefix not 

— a infix and, second operand evaluated only if first is true 

— o infix or, second operand evaluated only if first is false 

( expression ) parentheses for grouping. (Must be escaped.) 


To remove files named ‘a.out’ and ‘*.o’ not accessed for a week: 


find / "(" -name a.out -o -name "*.o" ")" -a -atime +7 -a -exec rm {) 


FILES 

/etc/passwd 
SEE ALSO 

sh (I), if(I), file system (V) 


BUGS 

There is no way to check device type. 
Syntax should be reconciled with if. 
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NAME 

form — form letter generator 

SYNOPSIS 

form proto arg ... 

DESCRIPTION 

Form generates a form letter from a prototype letter, an associative memory, arguments and in a 
special case, the current date. 

If form is invoked with the proto argument x, the associative memory is searched for an entry 
with name x and the contents filed under that name are used as the prototype. If the search 
fails, the message '[x]:’ is typed on the console and whatever text is typed in from the console, 
terminated by two new lines, is used as the prototype. If the prototype argument is missing! 
‘{letter}’ is assumed. 

Basically, .form is a copy process from the prototype to the output file. If an element of the form 
M (where n is a digit from 1 to 9) is encountered, the /7-th argument is inserted in its place, and 
that argument is then rescanned. If [0] is encountered, the current date is inserted. If the desired 
argument has not been given, a message of the form '[«]:’ is typed. The response typed in then is 
used for that argument. 

If an element of the form [name] or [name] is encountered, the name is looked up in the associa- 
tive memory. If it is found, the contents of the memory under this name replaces the original 
element (again rescanned). If the name is not found, a message of the form '[name]:' is typed. 
The response typed in is used for that element. The response is entered in the memory under 
the name if the name is enclosed in [ ]. The response is not entered in the memory but is 
remembered for the duration of the letter if the name is enclosed in {}. 

In both of the above cases, the response is typed in by entering arbitrary text terminated by two 
new lines. Only the first of the two new lines is passed with the text. 

If one of the special characters [{]}\ is preceded by a \, it loses its special character. 

If a file named ‘forma’ already exists in the user’s directory, ‘formb’ is used as the output file and 
so forth to ‘formz’. 

The file ‘form.m’ is created if none exists. . Because form.m is operated on by the disc allocator, 
it should only be changed by using fed, the form letter editor, or form. 


FILES 

form.m associative memory 
form? output file (read only) 

SEE ALSO 

fed (I), roff(I) 

BUGS 

An unbalanced ] or } acts as an end of file but may add a few strange entries to the associative 
memory. 
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NAME 

goto — command transfer 

SYNOPSIS 

goto label 

DESCRIPTION 

Goto is only allowed when the Shell is taking commands from a file. The file is searched from 
the beginning for a line beginning with V followed by one or more spaces followed by the label. 
If such a line is found, the goto command returns. Since the read pointer in the command file 
points to the line after the label, the effect is to cause the Shell to transfer to the labelled line. 

is a do-nothing command that is ignored by the Shell and only serves to place a label. 

SEE ALSO 

sh(I) 

BUGS 
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NAME 

grep — search a file for a pattern 
SYNOPSIS 

grep [ — v ] [ — b ] [ — c ] [ — n ] expression [ file ] ... 

DESCRIPTION 

Grep will search the input files (standard input default) for each line containing the regular ex- 
pression. Normally, each line found is printed on the standard output. If the — v flag is used, all 
lines but those matching are printed. If the — c flag is used, each line printed is preceded by its 
line number. If the — n flag is used, each line is preceded by the name of the input file and its 
relative line number in that file. If the — b flag is used, each line is preceded by the block 
number on which it was found. This is sometimes useful in locating disk block numbers by con- 
text. If interrupt is hit, the file and line number last searched is printed. 

For a complete description of the regular expression, see ed (I). Care should be taken when us- 
ing the characters S * [ “ | ( ) and \ in the regular expression as they are also meaningful to the 
Shell. It is generally necessary to enclose the entire expression argument in quotes. 

SEE ALSO 

ed (I), sh (I) 

BUGS 

Lines are limited to 512 characters; longer lines are truncated. 
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NAME 

if — conditional command 
SYNOPSIS 

if expr command [ arg ... ] 

DESCRIPTION 

If evaluates the expression expr, and if its value is true, executes the given command with the 
given arguments. 

The following primitives are used to construct the expr: 

— r file 
— w file 
si = s2 
si != s2 
{ command } 

These primaries may be combined with the following operators: 

! unary negation operator 

—a binary and operator 

—o binary or operator 

( expr ) parentheses for grouping. 

—a has higher precedence than — o. Notice that all the operators and flags are separate argu- 
ments to if and hence must be surrounded by spaces. Notice also that parentheses are meaning- 
ful to the Shell and must be escaped. 

SEE ALSO 

sh (I), find (I) 

BUGS 


true if tHe file exists and is readable, 
true if the file exists and is' writable, 
true if the strings si and s2 are equal, 
true if the strings si and s2 are not equal. 

The bracketed command is executed to obtain the exit status. Status zero is con- 
sidered true. The command must not be another if. 
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NAME 

kill — do in an unwanted process 
SYNOPSIS 

kill — [ signo ] processid ... 

DESCRIPTION 

Kills the specified processes. The processid of each asynchronous process started with '& is re- 
ported by the shell. Processid’s can also be found by using ps (I). 

The killed process must have been started from the same typewriter as the current user, unless 
he is the super-user. 

If a signal number preceded by is given as an argument, that signal is sent instead of kill (see 
signal (ID). 

SEE ALSO 

ps (I), sh (I), signal (II) 

BUGS 

Clearly people should only be allowed to kill processes owned by them, and having the same 
typewriter is neither necessary nor sufficient. 
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NAME 

Id — link editor 
SYNOPSIS 

Id [ — sulxrnd ] name ... 

DESCRIPTION 

Ld combines several object programs into one; resolves external references; and searches li- 
braries. In the simplest case the names of several object programs are given, and d combines 
them, producing an object module which can be either executed or become the input for a furth- 
er Id run. (In the latter case, the — r option must be given to preserve the relocation bits.) The 
output of Id is left on a.out. This file is executable only if no errors occurred during the load. 

The argument routines are concatenated in the order specified. The entry point of the-output is 
the beginning of the first routine. 

If any argument is a library, it is searched exactly once at the point it. is encountered in the argu- 
ment list. Only those routines defining ah unresolved external reference are loaded. If a routine 
from a library references another routine in the library, the referenced routine must appear after 
the. referencing routine in the library. Thus the order of programs within libraries is important. 

Ld understands several flag arguments which are written preceded by a \ Except for —1, they 
should appear before the file names. 

— s ‘squash’ the output, that is, remove the symbol table and relocation bits to save space (but 
impair the usefulness of the debugger). This information can also be removed by strip. 

— u take the following argument as a symbol and enter it as undefined in the symbol table. This 
Is useful for loading wholly from a library, since initially the symbol table is empty and an 
unresolved reference is needed to force the loading of the first routine. 

—1 This option is an abbreviation for a library name. —1 alone stands for ‘/lib/liba.a\ which is 
the standard system library for assembly language programs, —lx stands for ‘/lib/libx.a’ 
where x is any character. A library is searched when its name is encountered, so the place- 
ment of a —1 is significant. 

—x do not preserve local (non-.globl) symbols in the output symbol table; only enter external 
symbols. This option saves some space in the output file. 

— r generate relocation bits in the output file so that it can be the subject of another Id run. 
This flag also prevents final definitions from being given to common symbols. 

— d force definition of common storage even if the — r flag is present (used for reloc (VIII)). 

— n Arrange that when the output file is executed, the text portion will be read-only and shared 
among all users executing the file. This involves moving the data areas up the the first pos- 
sible 4K word boundary following the end of the text. 


FILES 

/lib/lib?. a libraries 
a.out output file 

SEE ALSO 

as(I), ar(I) 


BUGS 
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NAME 

In — make a link 
SYNOPSIS 

In namel [ name2 ] 

DESCRIPTION 

A link is a directory entry referring to a file; the same file (together with its size, all its protection 
information, etc) may have several links to it. There is no way to distinguish a link to a file 
from its original directory entry; any changes in the file are effective independently of the name 
by which the file is known. 

Ln creates a link to an existing file namel. If name2 is given, the link has that name; otherwise it 
is placed in the current directory and its name is the last component of namel. 

It is forbidden to link to a directory or to link across file systems. 

SEE ALSO 

rm(I) 


BUGS 

There is nothing particularly wrong with In, but tp doesn’t understand about links and makes one 
copy for each name by which a file is known; thus if the tape is extracted several copies are re- 
stored and the information that links were involved is lost. 
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NAME 

login — sign onto UNIX 

SYNOPSES 

login [ username ] 

DESCRIPTION 

The login command is used when a user initially signs onto UNIX, or it may be used at any time 
to change from one user to another. The latter case is the one summarized above and described 
here. See ‘How to Get Started’ for how to dial up initially. 

If login is invoked without an argument, it will ask for a user name, and, if appropriate, a pass- 
word. Echoing is turned off (if possible) during the typing of the password, so it will not appear 
on the written record of the session. 

After a successful login, accounting files are updated and the user is informed of the existence of 
mailbox and message-of-the-day files. 

Login is recognized by the Shell and executed directly (without forking). 


FILES 

/tmp/utmp accounting 

/usr/adm/wtmp accounting 
mailbox mail 

/etc/motd message-of-the-day 

/etc/passwd password file 

SEE ALSO 

init (VIII), getty (VIII), mail (I) 

DIAGNOSTICS 

‘login incorrect,’ if the name or the password is bad. ‘No Shell,’, ‘cannot open password file,’ ‘no 
directory’: consult a UNIX programming counselor. 

BUGS 

If the first login is unsuccessful, it tends to go into a state where it won’t accept a correct login. 
Hit EOT and try again. 
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NAME 

Is — list contents of directory 
SYNOPSIS 

Is [ — Itasdruif ] name ... 

DESCRIPTION 

For each directory argument. Is lists the contents of the directory; for each file argument, Is re- 
peats its name and any other information requested. The output is sorted alphabetically by de- 
fault. When no argument is given, the current directory is listed. When several arguments are 
given, the arguments are first sorted appropriately, but file arguments appear before directories 
and their contents. There are several options: 

—1 list in long format, giving mode, number of links, owner, size in bytes, and time of last 
modification for each file. (See below.) If the file is a special file the size field will instead 
contain the major and minor device numbers. 

— t sort by time modified (latest first) instead of by name, as is normal 

—a list all entries; usually those beginning with V are suppressed 

— s give size in blocks for each entry 

— d if argument is a directory, list only its name, not its contents (mostly used with —1 to get 
status on directory) 

— r reverse the order of sort to get reverse alphabetic or oldest first as appropriate 
— u use time of last access instead of last modification for sorting (— t) or printing (—1) 

— i print i-number in first column of the report for each file listed 

— f force each argument to be interpreted as a directory and list the name found in each slot. 
This option turns off —1, — t, — s, and — r, and turns on —a; the order is the order in which 
entries appear in the directory. • 

The mode printed under the —I option contains 10 characters which are interpreted as follows: 
the first character is 

d if the entry is a directory; 
b if the entry is a block-type special file; 
c if the entry is a character-type special file; 

— if the entry is a plain file. 

The next 9 characters are interpreted as three sets of three bits each. The first set refers to own- 
er permissions; the next to permissions to others in the same user-group; and the last to ali oth- 
ers. Within each set the three characters indicate permission respectively to read, to write, or to 
execute the file as a program. For a directory, ‘execute’ permission is interpreted to mean per- 
mission to search the directory for a specified file. The permissions are indicated as follows: 

r if the file is readable 
w if the file is writable 
x if the file is executable 

— if the indicated permission is not granted 

Finally, the group-execute permission character is given as s if the file has set-group-ID mode; 
likewise the user-execute permission character is given as s if the file has set-user-ID mode. 

FILES 

/etc/passwd to get user ID’s for Is —I. 

BUGS 
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NAME 

mail — send mail to another user 

SYNOPSIS 

mail [ — yn ] 
mail letter person ... 
mail person 

DESCRIPTION 

Mail without an argument searches for a file called mailbox, prints it if present, and asks if it 
should be saved. If the answer is y, the mail is renamed mbox, otherwise it is deleted. Mail 
with a — y or — n argument works the same way, except that the answer to the question is sup- 
plied by the argument. 

When followed by the names of a letter and one or more people, the letter is prepended to each 
person’s mailbox. When a person is specified without a letter, the letter is taken from the sender’s 
standard input up to an EOT. Each letter is preceded by the sender’s name and a postmark. 

A person is either a user name recognized by login, in which case the mail is sent to the default 
working directory of that user, or the path name of a directory, in which case mailbox in that 
directory is used. 

When a user logs in he is informed of the presence of mail. 

FILES 

/etc/passwd to identify sender and locate persons 

mailbox input mail 

mbox saved mail 

/tmp/mtm? temp file 

SEE ALSO 

login (I) 

BUGS 
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MAN(I) 


NAME 

man — run off section of UNIX manual 


SYNOPSIS 

man [ section ] [ title ... ] 


DESCRIPTION 

Man is a shell command file that will locate and run off one or more sections of this manual. 
Section is the section number of the manual, as an Arabic not Roman numeral, and is optional. 
Title is one or more section names; these names bear a generally simple relation to the page cap- 
tions in the manual. If the section is missing, 1 is assumed. For example, 

man man 

would reproduce this page. 

FILES 

/usr/man/man?/* 


BUGS 

The manual is supposed to be reproducible either on the phototypesetter or on a typewriter. 
However, on a typewriter some information is necessarily lost. 
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MESG(l) 


NAME 

mesg — permit or deny messages 

SYNOPSIS 

mesg [ n ] [ y ] 

DESCRIPTION 

Mesg with argument n forbids messages via write by revoking non-user write permission on the 
user’s typewriter. Mesg with argument y reinstates permission. All by itself, mesg reverses the 
current permission. In all cases the previous state is reported. 

FILES 

/dev/tty? 

SEE ALSO 

write (I) 

DIAGNOSTICS 

*?’ if the standard input file is not a typewriter 

BUGS 
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MKDIR(I) 


NAME 

mkdir — make a directory 

SYNOPSIS 

mkdir dirname ... 

DESCRIPTION 

Mkdir creates specified directories in mode 777. The standard entries V and are made au- 
tomatically. 

SEE ALSO 

rmdiKD 


BUGS 
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MV (I) 


NAME 


mv — move or rename a file 


SYNOPSIS 

mv namel name2 

DESCRIPTION 

Mv changes the name of namel to name2. If name2 is a directory, namel is moved to that direc- 
tory with its original file-name. Directories may only be moved within the same parent directory 
Oust renamed). 

If name2 already exists, it is removed before namel is renamed. If name2 has a mode which for- 
bids writing, mv prints the mode and reads the standard input to obtain a line; if the line begins 
with y, the move takes place; if not, mv exits. 

If name2 would lie on a different file system, so that a simple rename is impossible, mv copies the 
file and deletes the original. 

BUGS 

It should take a — f flag, like rm, to suppress the question if the target exists and is not writable. 
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NAME 

neqn — typeset mathematics on terminal 

SYNOPSIS 

neqn [ file ] ... 


DESCRIPTION 

Neqn is an nroff (I) preprocessor. The input language is the same as that of eqn (I). Normal 
usage is almost always 

neqn file ... | nroff 

Output is meant for terminals with forward and reverse capabilities, such as the Model 37 tele- 
type or GSI terminal. 

If no arguments are specified, neqn reads the'standard input, so it may be used as a filter. 

SEE ALSO 

eqn (I), gsi (VI) 

BUGS 

Because of some interactions with nroff there may not always be enough space left before and 
after lines containing equations. 
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NAME 

nice — run a command at low priority 
SYNOPSIS 

nice command [ arguments ] 
DESCRIPTION 

Nice executes command at low priority. 

SEE ALSO 

nohup(I), nice(II) 


BUGS 
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NAME 

nm — print name list 
SYNOPSIS 

nm [ — cnru ] [ name ] 

DESCRIPTION 

Nm prints the symbol table from the output file of an assembler or loader run. Each symbol 
name is preceded by its value (blanks if undefined) and one of the letters U (undefined) A (abso- 
lute) T (text segment symbol), D (data segment symbol), B (bss segment symbol), or C (common 
symbol). If the symbol is local (non-external) the type letter is in lower case. The output is sort- 
ed alphabetically. 

If no file is given, the symbols in a.out are listed. 

Options are: 

—c list only C-style external symbols, that is those beginning with underscore 
— n sort by value instead of by name 
- r sort in reverse order 
— u print only undefined symbols. 

FILES 

a.out 


BUGS 
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NOHUP(I) 


NAME 

nohup — run a command immune to hangups 
SYNOPSIS 

nohup command [ arguments ] 

DESCRIPTION 

Nohup executes command with hangups, quits and interrupts all ignored. 

SEE ALSO 

nice(I), signal(ll) 


BUGS 
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NAME 

nroff — format text 
SYNOPSIS 

nroff [+«][—«][ — nn ] [ — mx ] [ — s ] [ — h ] [ — q ] [ — i ] files 
DESCRIPTION 

Nroff formats text according to control lines embedded in the text files. Nroff will read the stan- 
dard .input if no file arguments are given. The non-file option arguments are interpreted as 
follows: 

+n Output will commence at the first page whose page number is n or larger. 

—n will cause printing to stop after page n. 

— n n First generated (not necessarily printed) page is given number n; simulates “.pn n". 

— mx Prepends a standard macro file; simulates “.so /usr/lib/tmac.x”. 

— s Stop prior to each page to permit paper loading. Printing is restarted by typing a ‘new- 

line’ character. 

— h Spaces are replaced where possible with tabs to speed up output (or reduce the size of 
the output file). 

— q Prompt names for insertions are not printed and the bell character is sent instead; the 

insertion is not echoed. 

— i Causes the standard input to be read after the files. 

FILES 

/usr/lib/suftab suffix hyphenation tables 
/tmp/rtm? temporary 
/usr/lib/tmac.? standard macro files 

SEE ALSO 

NROFF User’s Manual (internal memorandum), 
neqn (I) 


BUGS 
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REQUEST REFERENCE AND INDEX 


Request 

Initial 

If no 

Cause 


Form 

Value 

Argument 

Break 

Explanation 

1. Page Control 




.pi +N 

N=66 

N=66 

no 

Page length. 

.bp +N 

N=1 

- 

yes 

Begin page. 

.pn +N 

N=1 

ignored 

no 

Page number. 

.po +N 

N=0 

N=prev 

no 

Page offset. 

.ne N 

- 

N=1 

no 

Need N lines. 

.mk 

none 

- 

no 

Mark current line. 

.rt 

- 

- 

no 

Return to marked line. 

II. Text Filling, Adjusting, and Centering 


.br 

- 

- 

yes 

Break. 

.fi 

fill 

- 

yes 

Fill output lines. 

.Tlf 

fill 

- 

yes 

No filling and adjusting. 

.ad c 

adj,norm adjust 

no 

Adjust mode on. 

.na 

adjust 

- 

no 

No adjusting. 

.ce N 

off- 

N=1 

yes 

Center N input text lines. 

III. Line 

Spacing and 

Blank Lines 



.Is +N 

N=1 

N=prev 

no 

Line spacing. 

.sp N 

- 

N=1 

yes 

Space N lines 

.lv N 

- 

N=1 

no 

Save N lines 

.sv N 

- 

N=1 

no 

H 

•OS 

- 

- 

no 

Output saved lines. 

.ns 

space 

- 

no 

No-space mode on. 

.rs 

- 

- 

no 

Restore spacing. 

.xh 

off 

- 

no 

Extra-half-line mode on. 

IV. Line 

Length and 

Indenting 



.11 +N 

N=65 

N=prev 

no 

Line length. 

.in +N 

N=0 

N=prev 

yes 

Indent. 

.ti +N 

- 

N=1 

yes 

Temporary indent. 

V. Macros, Diversion, and Line Traps 


.de xx 

- 

ignored 

no 

Define or redefine a macro. 

.am xx 

- 

ignored 

no 

Append to a macro. 

.ds xx 

- 

ignored 

no 

Define or redefine string. 

.as xx 

- 

ignored no 

Append to a string. 

.rm xx 

- 

- 

no 

Remove macro name. 

.di xx 

- 

end 

no 

Divert output to macro "xx". 

.da xx 

- 

end 

no 

Divert and append to "xx". 

.wh -N xx 


- 

no 

When; set a line trap. 

.ch -N -M 

- 

- 

no 

Change trap line. 

.ch xx -M 

- 

- 

no 

n 

VI. Number Registers 



.nr ab +N 

-M 

- 

no 

Number register. 

.nr a +N ■ 

■M 

- 

no 

it 

.nc c 

\n 

\n 

no 

Number character. 

.ar 

arabic 

- 

no 

Arabic numbers. 

.ro 

arabic 

- • 

no 

Lower case roman numbers. 

.RO 

arabic 


no 

Upper case roman numbers. 
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VII. Input and Output Conventions and Character Translations 


.ta 

- 

none 

no 

Pseudotabs setting. 

.tc c 

space 

space 

no 

Tab replacement character. 

.lc c 


. ‘ 

no 

Leader replacement character. 

.ul n 

- 

N=1 

no 

Underline input text lines. 

.cc c 

• 


no 

Basic control character. 

.c2 c 

/ 

t 

no 

Nobreak control character. 

.ec c 

- 

\ 

no 

Escape character. 

.li N 

- 

N=1 

no 

Accept input lines literally. 

.tr abed.... 

- 

: 

no 

Translate on output. 

VIII. Hyphenation. 




.nh 

on 

- 

no 

No hyphenation. 

•hy 

on 

- 

no 

Hyphenate. 

.he c 

none 

none 

no 

Hyphenation indicator character. 

IX. Three Part Titles. 



, 

.tl 'left'center'right' 

. 

no 

Title. 

.UN 

N=65 

N=prev 

no 

Length of title. 

X. Output Line Numbering. 



,nm +N M S I 

off 

no 

Number mode on or off, set parameters. 

.npMSI 

- 

reset 

no 

Number parameters set or reset. 


XI. Conditional Input Line Acceptance 


.if !N anything 

no 

If true accept line of "anything". 

.if c anything 

no 

n 

.if !c anything 

no 

fi 

.if N anything 

no 

n 

XII. Environment Switching. 

.ev N N=0 N=prev 

no 

Environment switched (pushed down). 

XIII. Insertions from the Standard Input Stream 

1 

.rd prompt - . bell 

no 

Read insert. 

.ex 

no 

Exit. 

XIV. Input File Switching 

.so filename - 

no 

Switch source file (push down). 

.nx filename 

no 

Next file. 

XV. Miscellaneous 

.tm mesg 

no 

Typewriter message 

•ig 

no 

Ignore. 

.fl 

yes 

Flush output buffer. 

.ab - - 

no 

Abort. 
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NAME 


od — octal dump 


SYNOPSIS 

od [ — abcdho ] [ file ] [ [ + 1 offset! . ][ b ] ] 

DESCRIPTION 

Od dumps file in one or more formats as selected by the first argument. If the first argument is 
missing -o is default. The meanings of the format argument characters are: 

a interprets words as PDP-11 instructions and dis-assembles the operation code. Unknown 
operation codes print as ???. 

b interprets bytes in octal. 

c interprets bytes in ascii. Unknown ascii characters are printed as \?. 
d interprets words in decimal, 
h interprets words in hex. 
o interprets words in octal. 

The file argument specifies which file is to be dumped. If no file argument is specified, the stan- 
dard input is used. Thus od can be used as a filter. 

The offset argument specifies the offset in the file where dumping is to commence. This argu- 
ment is normally interpreted as octal bytes. If V is appended, the offset is interpreted in de- 
cimal. If ‘b’ is appended, the offset is interpreted in blocks. (A block is 512 bytes.) If the file ar- 
gument is omitted, the offset argument must be preceded by '+’. 

Dumping continues until end-of-file. 


SEE ALSO 

db (I) 

BUGS 


1 
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NAME 

passwd — set login password 
SYNOPSIS 

passwd name password 

\ 

DESCRIPTION 

The password is placed on the given login name: This can only be done by the person 
corresponding to the login name or by the super-user. An explicit null argument ("") for the 
password argument will remove any password from the login name. 

FILES 

/etc/passwd 
SEE ALSO 

login®, passwd(V), crypt(III) 

BUGS ■ ■ . ) 
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PFE(I) 


NAME 

pfe — print floating exception 

SYNOPSIS 

pfe 

DESCRIPTION 

Pfe examines the floating point exception register and prints a diagnostic for the last floating 
point exception. 


SEE ALSO 

signal GD 


BUGS 

Since the system does not save the exception register in a core image file, the message refers to 
the last error encountered by anyone. Floating exceptions are therefore volatile. 
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NAME 

pr — print file 
SYNOPSIS 

pr [ — h header ][—«][+/?][ — w n ] [ — In ] [ — t ] [ name . . . } 

DESCRIPTION 

Pr produces a printed listing of one or more files. The output is separated into pages headed by a 
dale, the name of the file or a header (if any), and the page number. If there are no file argu- 
ments, pr prints its standard input, and is thus usable as a filter. 

Options apply to all following files but may be reset between files: 

—n produce /7-column output 

+n begin printing with page n 

— h treat the next argument as a header 

— w n for purposes of multi-column output, take, the width of the page to be. n characters instead 
of the default 72 

—In take the length of the page to be n lines instead of the default 66 
— t do not print the 5-line header or the 5-line trailer normally supplied for each page 

If there is a header in force, it is printed in place of the file name. Interconsole messages via 
write(I) are forbidden during a pr. 

FILES 

/dev/tty? to suspend messages. 

SEE ALSO 

cat(I), cp(I) 

DIAGNOSTICS 

none; files not found are ignored 

BUGS 


\ 


; 


) 
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NAME 

prof — display profile data 
SYNOPSIS 

prof [ — v ][ — a ] [ -1 ] [ file ] 

DESCRIPTION 

Prof interprets the file mon.out produced by the monitor subroutine. Under default modes, the 
symbol table in the named object file (a.out default) is read and correlated with the mon.out 
profile file. For each external symbol, the percentage or time spent executing between that sym- 
bol and the next is printed (in decreasing order), together with the number of times that routine 
was called and the number of milliseconds per call. 

If the —a option is used, all symbols are 'reported rather than just external symbols. If the —I 
option is used, the output is listed by symbol value rather than decreasing percentage. If the — v 
option is used, all printing is suppressed and a profile plot is produced on the 611 display. 

In order for the number of calls to a routine to be tallied, the — p option of cc must have been 
given when the file containing the routine was compiled. 

FILES 

mon.out 
a.out 
/dev/vtO 

SEE ALSO 

monitordll), profilGD, ccG) 

BUGS 


for profile 
for namelist 
for plotting 
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NAME 

ps — process status . 

SYNOPSIS 

ps [ aklx ] 

DESCRIPTION 

Ps prints certain indicia about active processes. The a flag asks for information about all 
processes with teletypes (ordinarily only one’s own processes are displayed); x asks even about 
processes with no typewriter; 1 asks for a long listing. Ordinarily only the typewriter number (if 
not one’s own), the process number, and an approximation to the command line are given. If 
the k flag is specified, the special file IdevIrkO is used in place of /dev/mem. This is used for post- 
mortem system debugging. 

The long listing is columnar and contains 

A number encoding the stale (last digit) and flags (first 1 or 2 digits) of the process. 

The priority of the process; high numbers mean low priority. 

A number related in some unknown way to the scheduling heuristic. 

The last character of the control typewriter of the process. 

The process unique number (as in certain cults it is possible to kill a process if you know 
its true name). 

The size in blocks of the core image of the process. 

The last column if non-blank tells the core address in the system of the event which the 
process is waiting for; if blank, the process is running. 

Ps makes an educated guess as to the file name and arguments given when the process was creat- 
ed by examining core memory or the swap area. The method is inherently somewhat unreliable 
and in any event a process is entitled to destroy this information, so the names cannot be count- 
ed on loo much. 

FILES 

/unix system namelist 
/dev/mem core memory 

/dev/rfO swap device 

/dev/rkO optional mem file 

SEE ALSO 

kill (1) 

BUGS 

The command has assumptions built into it about the number of typewriters that exist and what 
hardware is used to interface them. It also has built into it the name of the device used for 
swapping. 
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PVVD(I) 


NAME 

pwd — print working directory pathname 

SYNOPSIS 

pwd 

DESCRIPTION 

Pwd prints the pathname of the working (current) directory. 

SEE ALSO 

chdir (I) 

BOGS 

The algorithm sometimes fails on crossing mounted file systems. 



REW(I) 


1/15/73 


REW(I) 


NAME 

rew — rewind tape 


SYNOPSIS 

rew [ [ m Idigit ] 


DESCRIPTION 

Rew rewinds DECtape or magtape drives. The digit is the logical tape number, and should range 
from 0 to 7. if the digit is preceded by m, rew applies to magtape rather than DECtape. A miss- 
ing digit indicates drive 0. 


FILES 

/dev/tap? 

/dev/mt? 

BUGS 
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NAME 

rm — remove (unlink) files 
SYNOPSIS 

rm [ -f ] ( -r 1 name ... 

DESCRIPTION i( . , , 

Rm removes the entries for one or more files from a directory. If an entry was the last link to 
the file, the file is destroyed. Removal of a file requires write permission in its directory, but nei- 
ther read nor write permission on the file itself. 

If there is no write permission to a file designated to be removed, rm will print the file name, its 
mode and then read a line from the standard input. If the line begins with y, the file is removed, 
otherwise it is not. The optional argument — f prevents this interaction. 

If a designated file is a directory, an error comment is printed unless the optional argument — r 
has been used. In that case, rm recursively deletes the entire contents of the specified directory. 
To remove directories per se see rmdir(I). 


FILES 

/etc/glob to implement the — r flag 

SEE ALSO 

rmdirCD 

BUGS • . 

When rm removes the contents of a directory under the — r flag, full pathnames are not printed 

in diagnostics. 





RMDIR(I) 


3 / 15/72 


RMDIR(l) 


NAME 

rmdir — remove directory 

SYNOPSIS 

rmdir dir ... 


DESCRIPTION 

Rmdir removes (deletes) directories. The directory must be empty (except for the standard en- 
tries V and which rmdir itself removes). Write permission is required in the directory in 
which the directory appears. 


BUGS 


Needs a — r flag. Actually, write permission in the directory’s parent is not required. 
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NAME 

roff — format text 
SYNOPSIS 

roff [ +n ] t — n ] [ — s ] [ — h ] file ... 

DESCRIPTION 

Roff formats text according to control lines embedded in the text in the given files. Encounter- 
ing a nonexistent file terminates printing. Incoming interconsole messages are turned off during 
printing. The optional flag arguments mean: 

+ n Start printing at the first page with number n. 

—n Stop printing at the first page numbered higher than n. 

— s Stop before each page (including the first) to allow paper manipulation; resume on receipt of 
an interrupt signal. 

— h Insert tabs in the output stream to replace spaces whenever appropriate. 

A Request Summary is attached. 

FILES 

/usr/lib/suftab suffix hyphenation tables 
/tmp/rtm? temporary 

SEE ALSO 

nroff (I), troff (I) 

BUGS 

Roff is the simplest bf the runoff programs, but is virtually undocumented. 
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REQUEST SUMMARY 


Request 

Break 

Initial 

Meaning 

.ad 

yes 

yes 

Begin adjusting right margins. 

.ar 

no 

arabic 

Arabic page numbers. 

.br 

yes 

- 

Causes a line break — the filling of the current line is stopped. 

.bl n 

yes 

- 

Insert of n blank lines, on new page if necessary. 

.bp +n 

yes 

n=l 

Begin new page and number it n; no n means ‘+1\ 

.cc c 

no 

c= 

Control character becomes ‘c’. 

.ce n 

yes 

- 

Center the next n input lines, without filling. 

.de xx 

no 

- 

Define macro named ‘xx’ (definition ends on line beginning 

.ds 

yes 

no 

Double space; same as ‘.Is 2’. 

.ef t 

no 

t="" 

Even foot title becomes t. 

.eh t 

no 

t="" 

Even head title becomes t. 

.fi 

yes 

yes 

Begin filling output lines. 

.fo 

no 

t="" 

All foot titles are t. 

.he c 

no 

none 

Hyphenation character set to ‘c\ 

.he t 

no 

t="" 

All head titles are t. , 

.hx 

no 

- 

Title lines are suppressed. 

.hy n 

no 

n=l 

Hyphenation is done, if n=l; and is not done, if n=0. 

•ig 

no 

- 

Ignore input lines through a line, beginning with 

.in +n 

yes 

- 

Indent n spaces from left margin. 

.ix +n 

no 

- 

Same as ‘.in’ but without break. 

.li n 

no 

- 

Literal, treat next n lines as text. 

.11 +n 

no 

n=65 

Line length including indent is n characters. 

.Is +n 

yes 

n=l 

Line spacing set to n lines per output line. 

.ml n 

no 

n=2 

Put n blank lines between the top of page and head title. 

.m2 n 

no 

n=2 

n blank lines put between head title and beginning of text on page. 

.m3 n 

no 

n=l 

n blank lines put between, end of text and foot title. 

,m4 n 

no 

n=3 

n blank lines put between the toot title and the bottom of page. 

.na 

yes 

no 

Stop adjusting the right margin. 

.ne n 

no 

- 

Begin new page, if n output lines cannot fit on present page. 

.nn +n 

no 

- 

The next n output lines are not numbered. 

.nl 

no 

no 

Number output lines; start with 1 each page 

.n2 n 

no 

no 

Number output lines; stop numbering if n=0. 

.ni +n 

no 

n=0 

Line numbers are indented n. 

.nf 

yes 

no 

Stop filling output lines. 

.nx filename 

- 

Change to input file ‘filename’. 

.of t 

no 

t-"" 

Odd foot title becomes t. 

.oh t 

no 

t="" 

Odd head title becomes t. 

.pa +n 

yes 

n=l 

Same as ‘.bp’. 

.pi +n 

no 

n=66 

Total paper length taken to be n lines. 

.po +n 

no 

n=0 

Page offset. All lines are preceded by N spaces. 

.ro 

no 

arabic 

Roman page numbers. 

.sk n 

no 

- 

Produce n blank pages starting next page. 

.sp n 

yes 

- 

Insert block of n blank lines. 

.ss 

yes 

yes 

Single space output lines, equivalent to Ms 1’. 

.ta N M .. 


- 

Pseudotab settings. Initial tab settings are columns 9,17,25,... 

.tc c 

no 

c=‘ ’ 

Tab replacement character becomes ‘c’. 

.ti +n 

yes 

- 

Temporarily indent next output line n space. 

.tr abed.. 

no 

- 

Translate a into b, c into d, etc. 

.ul n 

no 

- 

Underline the letters and numbers in the next n input lines. 


) 
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NAME 

sh — shell (command interpreter) 

SYNOPSIS 

sh [ name [ argl ... [ arg9 ] ] ] 

DESCRIPTION 

Sh is the standard command interpreter. It is the program which reads and arranges the execu- 
tion of the command lines typed by most users. It may itself be called as a command to inter- 
pret files of commands. Before discussing the arguments to the Shell used as a command, the 
structure of command lines themselves will be given. 

Commands. Each command is a sequence of non-blank command arguments separated by 
blanks. The first argument specifies the name of a command to be executed. Except for certain 
types of special arguments discussed below, the arguments other than the command name are 
passed without interpretation to the invoked command. 

If the first argument is the name of an executable file, it is invoked; otherwise the siring ‘/bin/’ is 
prepended to the argument. (In this way most standard commands, which reside in ‘/bin’, are 
found.) If no such command is found, the string ‘/usr’ is further prepended (to give 
‘/usr/bin/command’) and another attempt is made to execute the resulting file. (Certain lesser- 
used commands live in ‘/usr/bin’.) If the ‘/usr/bin’ file exists, but is not executable, it is used by 
the Shell as a command file. That is to say it is executed as though it were typed from the con- 
sole. If all attempts fail, a diagnostic is printed. 

Command lines. One or more commands separated by f or constitute a chain of filters. The 
standard output of each command but the last is taken as the standard input of the next com- 
mand. Each command is run as a separate process, connected by pipes (see pipe(II)) to its neigh- 
bors. A command line contained in parentheses '( )’ may appear in place of a simple command 
as a filler. 

A command line consists of one or more pipelines separated, and perhaps terminated by or ‘&\ 
The semicolon designates sequential execution. The ampersand causes the preceding pipeline to 
be executed without waiting for it to finish. The process id of such a pipeline is reported, so that 
it may be used if necessary for a subsequent wait or kill. 

Termination Reporting. If a command (not followed by '&’) terminates abnormally, a message is 
printed. (All terminations other than exit and interrupt are considered abnormal.) Termination 
reports for commands followed by are given upon receipt of the first command subsequent to 
the termination of the command, or when a wait is executed. The following is a list of the ab- 
normal termination messages; 

Bus error 
Trace/BPT trap 
Illegal instruction 
IOT trap 
EMT trap 
Bad system call 
Quit 

Floating exception 
Memory violation 
Killed 

If a core image is produced, Core dumped’ is appended to the appropriate message. 

Redirection of I/O. There are three character sequences that cause the immediately following 
string to be interpreted as a special argument to the Shell itself. Such an argument may appear 
anywhere among the arguments of a simple command, or before or after a parenthesized com- 
mand list, and is associated with that command or command list. 
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An argument of the form ‘<arg’ causes the file ‘arg’ to be used as the standard input (file 
descriptor 0) of the associated command. 

An argument of the form ‘>arg’ causes file ‘arg’ to be used as the standard output (file descriptor 
1) for the associated command. ‘Arg’ is created if it did not exist, and in any case is truncated at 
the outset. 

An argument of the form ‘>>arg’ causes file ‘arg’ to be used as the standard output for the as- 
sociated command. If ‘arg’ did not exist, it is created; if it did exist, the command output is ap- 
pended to the file. 

For example, either of the command lines 

Is >junk; cat tail > >junk 
( Is; cat tail ) >junk 

creates, on file ‘junk’, a listing of the working directory, followed immediately by the contents of 
file ‘tail’. 

Either of the constructs ‘>arg’ or ‘>>arg’ associated with any but the last command of a pipe- 
line is ineffectual, as is ‘<arg’ in any but the first. 

In commands called by the Shell, file descriptor 2 refers to the standard output of the Shell be- 
fore any redirection. Thus filters may write diagnostics to a location where they have a chance 
to be seen. 

Generation of argument lists. If any argument contains any of the characters '?’, or ‘[’, it is 
treated specially as follows. The current directory is searched for files which match the given ar- 
gument. 

The character **’ in an argument matches any string of characters in a file name (including the 
null string). 

The character '?’ matches any single character in a file name. 

Square brackets *[...]’ specify a class of characters which matches any single file-name character in 
the class. Within the brackets, each ordinary character is taken to be a member of the class. A 
pair of characters separated by ‘— ’ places in the class each character lexically greater than or 
equal to the first and less than or equal to the second member of the pair. 

Other characters match only the same character in the file name. 

For example, ‘*’ matches all file names; ‘?’ matches all one-character file names; ‘[ab]*.s’ matches 
all file names beginning with ‘a’ or ‘b’ and ending with ‘.s’; ‘?[zi — m]’ matches all two-character 
file names ending with ‘z’ or the letters ‘i’ through ‘m’. 

If the argument with or ‘?’ also contains a 7’, a slightly different procedure is used: instead of 
the current directory, the directory used is the one obtained by taking the argument up to the last 
7’ before a ‘*’ or ‘?\ The matching process matches the remainder of the argument after this 7’ 
against the files in the derived directory. For example: ‘/usr/dmr/a*.s’ matches all files in directo- 
ry ‘/usr/dmr’ which begin with ‘a’ and end with ‘.s'. 

In any event, a list of names is obtained which match the argument. This list is sorted into al- 
phabetical order, and the resulting sequence of arguments replaces the single argument containing 
the ‘*\ '[’, or ‘?\ The same process is carried out for each argument (the resulting lists are not 
merged) and finally the command is called with the resulting list of arguments. 

For example: directory /usr/dmr contains the files al.s,'a2.s a9.s. From any directory, the 

command 

as /usr/dmr/a?.s 

calls as with arguments /usr/dmr/al.s, /usr/dmr/a2.s, ... /usr/dmr/a9.s in that order. 

Quoting. The character ‘\’ causes the immediately following character to lose any special mean- 
ing it may have to the Shell; in this way '<’, ‘>\ and other characters meaningful to the Shell 
may be passed as part of arguments. A special case of this feature allows the continuation of 
commands onto more than one line: a new-line preceded by ‘V is translated into a blank. 
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Sequences of characters enclosed in double (") or single O quotes are also taken literally. For 
example: 

Is pr — h "My directory" 

causes a directory listing to be produced by Is, and passed on to pr to be printed with the heading 
‘My directory’. Quotes permit the inclusion of blanks in the heading, which is a single argument 
to pr. 

Argument passing. When the Shell is invoked as a command, it has additional string processing 
capabilities. Recall that the form in which the Shell is invoked is 

sh [ name [ argl ... [ arg9 ] ] ] 

The name is the name of a file which will be read and interpreted. If not given, this subinslance 
of the Shell will continue to read the standard input file.^ 

In command lines in the file (not in command input), character sequences of the form ‘$n\ 
where n is a digit, are replaced by the nth argument to the invocation of the Shell (argn). ‘$0’ is 
replaced by name. 

End of file. An end-of-file in the Shell’s input causes it to exit. A side effect of this fact means 
that the way to log out from UNIX is to type an EOT. 

Special commands. The following commands are treated specially by the Shell. 
chdir is done without spawning a new process by executing sys chdir (U). 
login is done by executing /bin/login without creating a new process. 
wait is done- without spawning a new process by executing sys wait (II). 
shift is done by manipulating the arguments to the Shell, 
is simply ignored. 

Command file errors; interrupts. Any Shell-detected error, or an interrupt signal, during the ex- 
ecution of a command file causes the Shell to cease execution of that file. 

Process that are created with a ‘&’ ignore interrupts. Also if such a process has not redirected its 
input with a '<’, its input is automatically redirected to the zero length file /dev/null. 

FILES 

/etc/glob, which interprets *?’, and T. 

/dev/null as a source of end-of-file. 

SEE ALSO 

‘The UNIX Time-sharing System’, which gives the theory of operation of the Shell, 
chdir (I), login (I), wait (I), shift (I) 

BUGS 

There is no way to redirect the diagnostic output. 
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NAME 

shift — adjust Shell arguments 

SYNOPSIS 

shift 

DESCRIPTION 

Shift is used in Shell command files to shift the argument list left by 1, so that old $2 can now be 
referred to by $1 and so forth. Shift is useful to iterate over several arguments to a command 
file. For example, the command file 

: loop 

if Six = x exit 
pr — 3 $1 
shift 

goto loop 

prints each of its arguments in 3-column formal. 

Shift is executed within the Shell. 

SEE ALSO 

sh (I) 

BUGS 



\ 



SIZE (I) 


9 / 2/72 


SIZE (I) 


NAME 

size — size of an object file 

SYNOPSIS 

size [ object ... ] 


DESCRIPTION 

Size prints the (decimal) number of bytes required by the text, data, and bss portions, and their 
sum in octal and decimal, of each object-file argument. If no file is specified, a.out is used. 


BUGS 
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NAME 

sleep — suspend execution for an interval 

SYNOPSIS 

sleep time 

DESCRIPTION 

Sleep will suspend execution for time seconds. It is used to execute a command in a certain 
amount of time as in: 

(sleep 105; command)& 

Or to execute a command every so often as in this shell command file: 

: loop 
command 
• sleep 37 

goto loop . 

SEE ALSO 

sleepGD 

BUGS 

Time must be less than 65536 seconds. 
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NAME 

sort — sort or merge files 
SYNOPSIS 

sort [ — abdnrtx ] [ +pos [ — pos ] ] . . . [ —mo ] [ name ] . . . 

DESCRIPTION 

Sort sorts all the named files together and writes the result on the standard output. The name ’ 
means the standard input. The standard input is also used if no input file names are given. 
Thus sort may be used as a filter. 

The default sort key is -an entire line. Default ordering is lexicographic in ASCII collating se- 
quence, except that lower-case letters are considered the same as the corresponding upper-case 
letters. Non-ASCII bytes are ignored. The ordering is affected by the flags — abdnrt, one or more 
of which may appear: 

a Do not map lower case letters. 

b Leading blanks (spaces and tabs) are not included in fields. 

d ‘Dictionary’ order: only letters, digits and blanks are significant in ASCII comparisons. 

n An initial numeric string, consisting of optional minus sign, digits and optionally included 
decimal point, is sorted by arithmetic value. 

r Reverse the sense of comparisons. 

tx Tab character between fields is x. 

Selected parts of the line, specified by +pos and —pos, may be used as sort keys. Pos has the 
form m.n, where m specifies a number of fields to skip, and n a number of characters to skip 
further into the next field. A missing .n is taken to be 0. +pos denotes the beginning of the key; 
—pos denotes the first position after the key (end of fine by default). Jhe ordering rule may be 
overridden for a particular key by appending one or more of the flags abdnr to +pos. 

When no tab character has been specified, a field consists of nonblanks and any preceding 
blanks. Under the — b flag, leading blanks are excluded from a field. When a tab character has 
been specified, a field is a string ending with a tab character. 

When keys are specified, later keys are compared only when all earlier ones compare equal. 
Lines that compare equal are ordered with all bytes significant. 

These flag arguments are also understood: 

— m Merge only, the input files are already sorted. 

—o The next argument is the name of an output file to use instead of the standard output. This 
file may be the same as one of the inputs, except under the merge flag — m. 

. FILES 


/usr/tmp/stm??? 
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NAME 

spell — find spelling errors 

SYNOPSIS 

spell file ... 

DESCRIPTION 

Spell attacks the same problem as typo (I), but from the opposite direction. It extracts words 
from the input files and looks them up in Webster's Seventh Collegiate Dictionary; any words 
which appear neither in the dictionary nor in a list of about 2000 words frequently occurring in 
Bell Laboratories documents are listed on the output file sp.out. Words which are reasonable 
transformations of dictionary entries (e.g. a dictionary entry plus 5 ) are so marked; words which 
could not be found even when transformed are marked with asterisks. 

The process takes on the order of 5 to 10 minutes. There is a limit of nine input files. 

FILES ^ 

/usr/lib/w2006, /usr/dict/words, sp.out; spjnkq[123] are temporaries. 

SEE ALSO 

typo (I) 

BUGS 

There should be no limit on the number of input files. 

More suffixes, and perhaps some prefixes, should be added. 

It should be usable as a filter. 
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NAME 

split — split a file into pieces 
SYNOPSIS 

split —n [ file [ name ] ] 


DESCRIPTION 

Split reads file and writes it in fl-line pieces (default 1000), as many as necessary, onto a set of 
output files. The name of the first output file is name with aa appended, and so on lexicographi- 
cally. If no output name is given, x is default 

If no input file is given, or if — is given in its stead, then the standard input file is used. 


BUGS 
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NAME 

strip — remove symbols and relocation bits 

SYNOPSIS 

strip name ... 


DESCRIPTION 

Strip removes the symbol table and relocation bits ordinarily attached to the output of the assem- 
bler and loader. This is useful to save space after a program has been debugged. 

The effect of strip is the the same as use of the — s option of Id. 


FILES 

/tmp/stm? temporary file 

SEE ALSO 

ld(I), as(I) 


BUGS 
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NAME 

stly — set typewriter options 

SYNOPSIS 

stty option ... 

DESCRIPTION 

•SV/y.will set certain I/O options on the current output typewriter. The option strings are selected 
from the following set: 

even 
—even 
odd 
—odd 
raw 
—raw 
-nl 
nl 

echo 
—echo 
lease 
—lease 
—tabs 
tabs 
delay 
—delay 
tdelay 
— tdelay 

SEE ALSO 

stty (II) 

BUGS 

There should be ‘package’ options such as execuport, 33, or terminet. 


allow even parity 
disallow even parity 
allow odd parity 
disallow odd parity 

raw mode input (no erase, kill, interrupt, quit, EOT; parity bit passed back) 
negate raw mode 

allow carriage return for new-line, and output CR-LF for carriage return or new-line 

accept only new-line to end lines 

echo back every character typed 

do not echo characters 

map upper case to lower case 

do not map case 

replace tabs by spaces in output 

preserve tabs 

calculate cr, tab, and form-feed delays 
no cr/tab/ff delays 
calculate tab delays 
no tab delays 
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NAME 

sum — sum file 


SYNOPSIS 

sum name ... 


DESCRIPTION 

Sum sums the contents of the bytes (mod 2"16) of one or more files and prints the answer in oc- 
tal. A separate sum is printed for each file specified, along with the number of whole or partial 
512-byte blocks read. 

In practice, sum is often used to verify that all of a special file can be read without error. 

BUGS 
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NAME 

tee — pipe fitting 

SYNOPSIS 

tee [ name ... ] 

DESCRIPTION 

Tee transcribes the standard input to the standard output and makes copies in the named files. 


BUGS 
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NAME 

time — time a command 

SYNOPSIS 

time command 


DESCRIPTION 

The given command is executed; after it is complete, time prints the elapsed time during the 
command, the time spent in the system, and the time spent in execution of the command. 

The execution time can depend on what kind of memory the program happens to land in; the 
user time in MOS is often half what it is in core. 

The times are printed on the diagnostic output stream. 

BUGS 

Elapsed time is accurate to the second, while the CPU limes are measured to the 60th second. 
Thus the sum of the CPU times can be up to a second larger than the elapsed time. 
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NAME * 

tp — manipulate DECtape and magtape 

SYNOPSIS 

tp t key ] [ name ... ] 

DESCRIPTION 

Tp saves and restores selected portions of the file system hierarchy on DECtape or mag tape. Its 
actions are controlled by the key argument. The key is a string of characters containing at most 
one function letter and possibly one or more function modifiers. Other arguments to the com- 
mand are file or directory names specifying which files are to be dumped, restored, or listed. 

The function portion of the key is specified by one of the following letters: 

r The indicated files and directories, together with all subdirectories, are dumped onto the 
tape. If files with the same names already exist, they are replaced. ‘Same’ is deter- 
mined by string comparison, so ‘./abc’ can never be the same as ‘/usr/dmr/abc’ even if 
‘/usr/dmr’ is the current directory. If no'file argument is given, V is the default. 

u updates the tape, u is the same as r, but a file is replaced only if its modification date is 

later than the date stored on the tape; that is to say, if it has changed since it was 

dumped, u is the default command if none is given. 

d deletes the named files and directories from the tape. At least one file argument must 
be given. This function is not permitted on magtapes. 

x extracts the named files from the tape to the file system. The owner, mode, and date- 

modified are restored to what they were when the file was dumped. If no file argument 
is given, the entire contents of the tape are extracted. 

t lists the names of all files stored on the tape which are the same as or are hierarchically 
below the file arguments. If no file argument is given, the entire contents of the tape is 
listed. 

The following characters may be used in addition to the letter which selects the function desired. 

m Specifies magtape as opposed to DECtape. 

0,...,7 This modifier selects the drive on which the tape is mounted. For DECtape, ‘x’ is 
default; for magtape ‘0’ is the default. 

v Normally tp does its work silently. The v (verbose) option causes it to type the name 
of each file it treats preceded by the function letter. With the t function, v gives 
more information about the tape entries than just the name. 

c means a fresh dump is being created; the tape directory will be zeroed before begin- 
ning. Usable only with r and u. This option is assumed with magtape since it is im- 
possible to selectively overwrite magtape. 

f causes new entries on tape to be ‘fake’ in that no data is present for these entries. 
Such fake entries cannot be extracted. Usable only with r and u. 

i Errors reading and writing the tape are noted, but no action is taken. Normally, er- 
rors cause a return to the command level. - 

w causes tp to pause before treating each file, type the indicative letter and the file name 
(as with v) and await the user’s response. Response y means ‘yes’, so the file is treat- 
ed. Null response means ‘no’, and the file does not take part in whatever is being 
done. Response x means ‘exit’; the tp command terminates immediately. In the x 
function, files previously asked about have been extracted already. With r, u, and d 
no change has been made to the tape. 

FILES 

/dev/tap? 

/dev/mt? 
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DIAGNOSTICS 

Several; the non-obvious one is ‘Phase error’, which means the file changed after it was selected 
for dumping but before it was dumped. 

BUGS ^ 

J 
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NAME 

tr — transliterate 
SYNOPSIS 

tr [ — cds ] [ stringl [ string2 ] ] 

DESCRIPTION 

Tr copies the standard input to the standard output with substitution or deletion of selected char- 
acters. Input characters found in stringl are mapped into the corresponding characters of string2. 
If string2 is short, it is padded with corresponding characters from stringl. Any combination of 
the options —cds may be used. — c complements the set of characters in stringl with respect to 
the universe of characters whose ascii codes are 001 through 377 octal. — d deletes all input char- 
acters in stringl. — s squeezes all strings of repeated output characters that are in strmg2 to single 
characters. 

The following abbreviation conventions may be used to introduce ranges of characters or repeat- 
ed characters into the strings: 

la— 61 stands for the string of characters whose ascii codes run from character a to character b. 

\a*n\, where n is an integer or empty, stands for w-fold repetition of character a. n is taken to be 
octal or decimal according as its first digit is or is not zero. A zero or missing n is taken to be 
huge; this facility is useful for padding string2. 

The escape character ‘V may be used as in sh to remove special meaning from any character in a 
string. In addition, ‘V followed by 1, 2 or 3 octal digits stands for the character whose ascii code 
is given by those digits. 

The following example creates a list of all the words in ‘filel’ one per line in ‘file2\ where a word 
is taken to be a maximal string of alphabetics. The strings are quoted to protect the special char- 
acters from interpretation by the Shell; 012 is the ascii code for newline. 

tr -cs "[A— Z][a— z]" "[\012*]" < filel >file2 

err at co 

sh 0), ed (I), ascii (VII) 

BUGS 

Won’t handle ascii NUL in stringl or string 2; always deletes NUL from input. 
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NAME 

troff — format text 
SYNOPSIS 

troff [+«][—«][ — nn ] [ — mx ] [ — t ] [ — f ] [ — w ] [ — i ] [ — a ] [ — p n ] files 
DESCRIPTION 

Troff formats text for a Graphic Systems phototypesetter according to control lines embedded in 
the text files. It reads the standard input if no file arguments are given. The non-file option ar- 
guments are interpreted as follows: 

+n Commence typesetting at the first page numbered n or larger. 

— n Stop after page n. 

—nn First generated (not necessarily printed) page is given the number n; simulates “.pn n". 
-nu Prepends a standard macro file; simulates “.so /usr/Iib/tmac.x”. 

— t Place output on standard output instead of the phototypeselter. 

— f Refrain from feeding out paper and stopping the phototypesetter at the end. 

— w Wait until phototypsetter is available, if currently busy. 

— i Read from standard input after the files have been exhausted. 

—a Send a printable approximation of the results to the standard output. 

—pn Print all characters with point-size n while retaining all prescribed spacings and motions. 

FILES * 

/usr/lib/suftab suffix hyphenation tables 
/tmp/rtm? temporary 
/usr/lib/tmac.x standard macro files 

SEE ALSO 

TROFF User’s Manual (internal memorandum). 

TROFF Made Trivial (internal memorandum), 
nroff (I), eqn (I) calsim (VI) 


BUGS 
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NAME 

tty — get typewriter name 
SYNOPSIS 

tty 

DESCRIPTION 

Tty gives the name of the user’s typewriter in the form ‘tty/i’ for n a digit or letter. The actual 
path name is then ‘/dev/ttyw’. 

DIAGNOSTICS 

‘not a tty’ if the standard input- file is not a typewriter. 


BUGS 
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NAME 

typo — find possible typos 
SYNOPSIS 

typo [ — 1 ] [ — n ] file ... 

DESCRIPTION 

Typo hunts through a document for unusual words, typographic errors, and hapax legomena and 
prints them on the standard output. 

The words used in the document are printed out in decreasing order of peculiarity along with an 
index of peculiarity. An index of 10 or more is considered peculiar. Printing of certain very 
common English words is suppressed. 

The statistics for judging words are taken from the document itself, with some help from known 
statistics of English. The -n option suppresses the help from English and should be used if the 
document is written in, for example, Urdu. 

The —1 option causes the final output to appear in a single column instead of three columns. 
The normal header and pagination is also suppressed. 

Roff (I) and nroff (I) control lines are ignored. Upper case is mapped into lower case. Quote 
marks, vertical bars, hyphens, and ampersands are stripped from within words. Words hy- 
phenated across lines are put back together. 

FILES 

/tmp/ttmp?? 

/usr/lib/salt 

/usr/lib/w2006 

BUGS 

Because of the mapping into lower case and the stripping of special characters, words may be 
hard to locate in the original text. 

The escape sequences of troff (I) are not correctly recognized. 
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NAME 

uniq — report repeated lines in a file 
SYNOPSIS 

uniq [ — udc [ +n ] [ — n ] ] [ input [ output ] ] 

DESCRIPTION 

Uniq reads the input file comparing adjacent lines. In the normal case, the second and succeed- 
ing copies of repealed lines are removed; the remainder is written on the output file. Note that 
repeated lines must be adjacent in order to be found; see sort(l).- If the — u flag is used, just the 
lines that are not repealed in the original file are output. The — d option specifies that one copy 
of just the repeated lines is to be written. The normal mode output is the union of the — u and 
— d mode outputs. - 

The — c option supersedes — u and — d and generates an output report in default style but with 
each line preceded by a count of the number of times it occurred. 

The n arguments specify skipping an initial portion of each line in the comparison: 

—n The first n fields together with any blanks before each are ignored. A field is defined as 
a string of non-space, non-tab characters separated by tabs and spaces from its neigh- 
bors. 

+n The first n characters are ignored. Fields are skipped before characters. 

SEE ALSO 

sort (I), comm (I) 


BUGS 
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NAME 

wait — await completion of process 

SYNOPSIS 

wait 


DESCRIPTION 

Wait until all processes started with & have completed, and report on abnormal terminations. 

Because sys wait must be executed in the parent process, the Shell itself executes wait, without 
creating a new process. 

SEE ALSO 

sh (I) 

BUGS 

After executing wait you are committed to waiting until termination, because interrupts and quits 
are ignored by all processes concerned. The only out, if the process does not terminate, is to kill 
it from another terminal or to hang up. 
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NAME 

wc — word count 


SYNOPSIS 

wc [ — rlwapc ] [ name ... ] 

DESCRIPTION 

Wc counts lines and words in the named files, or in the standard input if no name appears. A 
word is a maximal string of ascii graphics delimited by spaces, tabs or newlines. Other charac- 
ters are always ignored. 

Any of the following options may appear in any order. When any option other than — r appears, 
only the specified information is reported in the order in which the options occur. Otherwise, 
printing is as with option — Iw. 

• — r Ignore all roff, nroff and rro/fcontrol lines, i.e. lines beginning with or 
—I Print count of lines. 

— w Print count of words. 

—a Print count of alphanumeric strings, with underscore taken as alphanumeric. 

— p Print count of punctuation strings, i.e. all strings of printing characters other than al- 
phanumerics. 

— c Print count of roff control lines, regardless of — r. 

DIAGNOSTICS 

‘Cannot open’ for unopenable file. 

BUGS 
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NAME 

who — who is on the system 

SYNOPSIS 

who [ who-file ] 


DESCRIPTION 

iTMiv With0Ut an argument ’ ,ists the name ’ typewriter channel, and login time for each current 
unia user. 

Without an argument, who examines the /tmp/utmp file to obtain its information. If a file is 
given, that file is examined. Typically the given file will be /tmp/wtmp, which contains a record 
ot all the logins since it was created. Then who will list logins, logouts, and crashes since the 
creation of the wtmp file. 

Each login is listed with user name, typewriter name (with ‘/dev/ 1 suppressed), and date and time. 
When an argument is given, logouts produce a similar line without a user name. Reboots pro- 
duce a line with ‘x’ in the place of the device name, and a fossil time indicative of when the sys- 
tem went down. 

FILES 

/tmp/utmp 


SEE ALSO 

login (I), init (VIII) 

BUGS 
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NAME 

write — write to another user 
SYNOPSIS 

write user [ ttyno ] 

DESCRIPTION 

Write copies lines from your typewriter to that of another user. When first called, it sends the 
message 

message from yourname... 

The recipient of the message should write back at this point. Communication continues until an 
end of file is read from the typewriter or an interrupt is sent. At that point write writes ‘EOT’ 
on the other terminal and exits. 

If you want to write to a user who is logged in more than once, the ttyno argument may be used 
to indicate the last character of the appropriate typewriter name. 

Permission to write may be denied or granted by use of the mesg command. At the outset writ- 
ing is allowed. Certain commands, in particular roff and pr, disallow messages in order to 
prevent messy output. 

If the character T is found at the beginning of a line, write calls the mini-shell msh to execute the 
rest of the line as a command. 

The following protocol is suggested for using write: when you first write to another user, wait for 
him to write back before starting to send. Each party should end each message with a distinctive 
signal ( (o) for ‘over’ is conventional) that the other may reply, (oo) (for ‘over and out’) is sug- 
gested when conversation is about to be terminated. 

FILES 

/tmp/utmp to find user 

/etc/msh to execute *!’ 

SEE ALSO 

mesg(I), who(I) 

BUGS 
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ALLOC (III) 


3/1/74 


ALLOC (III) 


NAME 

alloc — core allocator 

SYNOPSIS 

char *aI!oc(size) 

free(ptr) 
char *ptr; 

DESCRIPTION 

Alloc and free provide a simple general-purpose core management package. Alloc is given a size 
in bytes; it returns a pointer to an area at least that size which is even and hence can hold an ob- 
ject of any type. . The argument to free is a pointer to an area previously allocated by alloc; this 
space is made available for further allocation. 

Needless to say, grave disorder will result if the space assigned by alloc is overrun or if some 
random number is handed to free. 

The routine uses a first-fit algorithm which coalesces blocks being freed with other blocks already 
free. It calls sbrk {, see break (ID) to get more core from the system when there is no suitable 
space already free, and writes “Out of space” on the standard output, then exits, if that fails. 

The external variable slop (which is 2 if not set) is a number such that if n bytes are requested, 
and if the first free block of size at. least n is no larger than n+slop, then the whole block will be 
allocated instead of being split up. Larger values of slop tend to reduce fragmentation at the ex- 
pense of unused space in the allocated blocks. 

DIAGNOSTICS 

“Out of space” if it needs core and can’t get it. 


BUGS 



‘ ATAN(III) 


4/30/73 


ATAN(HI) 



NAME 

atan — arc tangent function 

SYNOPSIS 

jsr r5,atan[2] 

double atan(x) 
double x; 

double atan2(x, y) 
double x, y; 

DESCRIPTION 

The atan entry returns the arc tangent of frO i.n frO; from C, the arc tangent of x is returned 
The range is -tt/2 to tt/2. The atan2 entry returns the arc tangent of frO/frl in frO; from C, the 
arc tangent of xly is returned. The range is —it to n. 

DIAGNOSTIC 

There is no error return. 


BUGS 



ATOF(III) 


4/30/73 


ATOF(III) 


. NAME 

atof — ascii to floating 

SYNOPSIS 

double atoffnptr) 
char *nptr; 

DESCRIPTION 

Atof converts a string to a floating number. Nptr should point to a string containing the number; 
the first unrecognized character ends the number. 

The only numbers recognized are; an optional minus sign followed by a string of digits optional- 
ly containing one decimal point, then followed optionally by the letter e followed by a signed in- 
teger. 

DIAGNOSTICS 

There' are none; overflow results in a very large number and garbage characters terminate the 
scan. 

BUGS 

The routine should accept initial +, initial blanks, and E for e. Overflow should be signalled. 







CRYPT(III) 


4/30/73 


CRYPT(III) 


NAME 


crypt — password encoding 


SYNOPSIS 

mov Skey,rO 
jsr pc.crypt 

char *crypt(key) 
char *key; 

DESCRIPTION 

On entry, rO should point to a string of characters terminated by an ASCII NULL. The routine 
performs an operation on the key which is difficult to invert (i.e. encrypts it) and leaves the 
resulting eight bytes of ASCII alphanumerics in a global cell called “word”. 

From C, the key argument is a string and the value returned is a pointer to the eight-character 
encrypted password. 

Login uses this result as a password. 

SEE ALSO 

passwd(I), passwd(V), login(I) 


-!- 


CTIME(III) 


10/15/73 


CTIME(III) 


NAME 

ctime — convert date and time to ASCII 

SYNOPSIS 

char *ctime(tvec) 
int tvecl2l; 

[from Fortran] 
double precision ctime 
... = ctime(dummy) 

int *localtime(tvec) 
int tvec[2|; 

int *gmtime(tvec) 
int tvec[2l; 

DESCRIPTION 

Ctime converts a lime in the vector tvec such as returned by lime (II) into ASCII and returns a 
pointer to a character string in the form 

Sun Sep 16 01:03:52 1973\n\0 
All the fields have constant width. 

Once the time has been placed into t and r+2. this routine is callable from assembly language as 
follows: 

mov St,— (sp) 

jsr pc,_ctime 

tst (spH- ~ - 

and a pointer to the string is available in rO. 

The localtime and gmiirrie entries return pointers to integer vectors containing the broken-down 
time. Localtime corrects for the lime zone and possible daylight savings time; gmtime converts 
directly to GMT, which is the lime UNIX uses. The value is a pointer to an array whose com- 
ponents are 

0 seconds • 

1 minutes 

2 hours 

3 day of the month (1-31) 

4 month (0-11) 

5 year — 1900 

6 day of the week (Sunday = 0) 

7 day of the year (0-365) 

8 Daylight Saving Time flag if non-zero 

The external variable timezone contains the difference, in seconds, between GMT and local stan- 
dard time (in EST, is 5*60*60); the external variable daylight is non-zero iff the standard U.S.A. 
Daylight Saving Time conversion should be applied between the last Sundays in April and Oc- 
tober. The external variable nixonflg if non-zero supersedes daylight and causes daylight lime all 
year round. 

A routine named ctime is also available from Fortran. Actually it more resembles the time (II) 
system entry in that it returns the number of seconds since the epoch 0000 GMT Jan. 1, 1970 (as 
a floating-point number). 

SEE ALSO 

time(Il) 

BUGS 
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ECVT(III) 


4/30/73 


ECVT(III) 


NAME 

ecvt — output conversion 

SYNOPSIS 

jsr pc,ecvt 

jsr pc,fcvt 

char *ecvt(value, ndigit, decpt, sign) 

double value; 

int ndigit, *decpt, *sign; 

char *fcvt(value, ndigit, decpt, sign) 


DESCRIPTION 

Ecvt is called with a floating point number in frO. 

On exit, the number has been converted into a string of ascii digits in a buffer pointed to by rO. 
The number of digits produced is controlled by a global variable _ndigits. 

Moreover, the position of the decimal point is contained in r2: r2=0 means the d.p. is at the left 
hand end of the string of digits; r2>0 means the d.p. is within or to the .right of the string. 

The sign of the number is indicated by rl (0 for +; 1 for — ). 

The low order digit has suffered decimal rounding (i. e. may have been carried into). 

From C, the value is converted and a pointer to a null-terminated siring of ndigit digits is re- 
turned. The position of the decimal point is stored indirectly through decpt (negative means to 
the left of the returned digits). If the sign of the result is negative, the word pointed to by sign is 
non-zero, otherwise it is zero. 

Fcvt is identical to ecvt , except that the correct digit has had decimal rounding for F-style output 
of the number of digits specified by ndigits. 

SEE ALSO 

printfflll) 

BUGS 



EXP(III) 


4/30/73 


EXP (III ) 


NAME 

exp — exponential function 

SYNOPSIS 

jsr r5,exp 

double exp(x) 
double x; 

DESCRIPTION 

The exponential of frO is returned in frO. From C, the exponential of x is returned. 


DIAGNOSTICS 

If the result is not representable, the c-bit is set and the largest positive number is returned. 
From C, no diagnostic is available. 

Zero is returned if the result would underflow. 


BUGS 


. FLOOR (III) 


5 / 15/74 


FLOOR (III) 



floor — floor and ceiling functions 


, SYNOPSIS 

double floor(x) 
double x; 

double ceil(x) 
double x; 



DESCRIPTION 

The floor function returns the largest integer (as a double precision number) not greater than x. 
The ceil function returns the smallest integer not less than x. 




FPTRAP(III) 


11/18/73 


FPTRAP(III) 


NAME 

fptrap — floating point interpreter 
SYNOPSIS 

sys signal; 4; fptrap 
DESCRIPTION 

Fptrap is a simulator of the 11/45 FP11-B floating point unit. It works by intercepting illegal in- 
struction faults and examining the offending operation codes for possible floating point. 

FILES 

found in /lib/libu.a; a fake version is in /lib/liba.a 
DIAGNOSTICS 

A break point trap is given when a real illegal instruction trap occurs. 

SEE ALSO 

signal(II) 

BUGS 

Rounding mode is not interpreted. It’s slow. 


GAMMA(III) 


5/15/74 


GAMMA (III) 


^fefNAME 

gamma — log gamma function 

* SYNOPSIS 

jsr r5,gamma 

double gamma(x) 
double x; 

DESCRIPTION 

If x is passed (in frO) gamma returns In |T(x)| (in frO). The sign of T(x) is returned in the exter- 
nal integer signgam. The following C program might be used to calculate T: 

y = gamma(x); 
if (y > 88.) 

erroK >, 
y = exp(y); 
iffsigngam) 

y = -y; 

DIAGNOSTICS 

x The c-bit is set on negative integral arguments and the maximum value is returned. There is no 

error return for C programs. 


BUGS 


No error return from C. 



GETARG(III) 


11/24/73 


GETARG(III) 


NAME 

getarg — gel command arguments from Fortran 
SYNOPSIS 

call getarg ( i, iarray [ , isize 1 ) 

... = iargcfdummy) 


The getarg entry fills in iarray (which is considered to be integer) with the Hollerith string 
representing the / th argument to the command in which it it is called. If no isize argument is 
specified, at least one blank is placed after the argument, and the last word affected is blank pad- 
ded. The user should make sure that the array is big enough. 

If the isize argument is given, the argument will be followed by blanks to fill up isize words, but 
even if the argument is long no more than that many words will be filled in. 

The blank-padded array is suitable for use as an argument to setfil (HI). 

The iargc entry returns the number of arguments to the command, counting the first (file-name) 
argument. 

SEE ALSO 

exec (II), setfil (III) 

BUGS 




I 



GETC(III) 


4/30/72 


GETC(III) 


NAME 

getc — buffered input 
SYNOPSIS 

mov $filename,rO 
jsr r5,fopen; iobuf 

fopen(filename, iobuf) 
char *filename; 
struct buf *iobuf; 


jsr r5,getc; iobuf 
(character in rO) 


getc(iobuO 
struct buf ’"iobuf; 


jsr r5,getw; iobuf 
(word in rO) 

getw(iobuf) 
struct buf ’"iobuf; 

DESCRIPTION 

These routines provide a buffered input facility. Iobuf is the address of a 518(10) byte buffer area 
whose contents are maintained by these routines. Its format is: 


ioptr: .=.+2 
.=.+2 
.=.+2 
.=.+512 


/ file descriptor 
/ characters left in buffer 
/ ptr to next character 
/ the buffer 


Or in C, 

struct buf { 

int tildes; 
int nleft; 
char *nextp; 
char buffer[512l; 

}; 

Fopen may be called initially to open the file. On return, the error bit (c-bit) is set if the open 
failed. If fopen is never called, get will read from the standard input file. From C, the value is 
negative if the open failed. 

Gere returns the next byte from the file in rO. The error bit is set on end of file or a read error. 
From C, the character is returned; it is —1 on end-of-file or error. 


Getw returns the next word in rO. Gere and getw may be used alternately; there are no odd/even 
problems. Getw is may be called from C; —1 is returned on end-of-file or error, but of course is 
also a legitimate value. 

Iobuf must be provided by the user; it must be on a word boundary. 

To reuse the same buffer for another file, it is sufficient to close the original file and call fopen 
again. 

SEE ALSO 

open(ll), read(Il), putc(III) 


DIAGNOSTICS 

c-bit set on EOF or error; 

from C, negative return indicates error or EOF. 




GETCHAR(III) 


4/7/73 


GETCHAR(III) 


NAME 

getchar — read character 

SYNOPSIS 

getchaK ) 

DESCRIPTION 

Getchar provides the simplest means of reading characters from the standard input for C pro- 
grams. It returns successive characters until end-of-file, when it returns “\0”. 

• Associated with this routine is an external variable called fin, which is a structure containing a 
buffer such as described under gerc (III). 

Generally speaking, getchar should be used only for the simplest applications; getc is better when 
there are multiple input files. 

SEE ALSO 

getc (III) 

DIAGNOSTICS 

Null character returned on EOF or error. 

BUGS 

—1 should be returned on EOF; null is a legitimate character. 



HMUL(III) 


4/7/73 


HMUL(III) 


NAME 

hmul — high-order product 

SYNOPSIS 

hmul(x, y) 

DESCRIPTION 

Hmul returns the high-order 16 bits of the product of x and y. CThe binary multiplication opera- 
tor generates the low-order 16 bits of a product.) 



HYPOT(III) 


6/12/72 


HYPOT(III) 


NAME 

hypot — calculate hypotenuse 

SYNOPSIS 

jsr r5, hypot 


DESCRIPTION 

The square root of frOxfrO 4- frl x frl is returned in frO. The calculation is done in such a 
way that overflow will not occur unless the answer is not representable in floating point. 


DIAGNOSTICS 

The c-bit is set if the result cannot be represented. 


BUGS 



IERROR(III) 


10/29/73 


IERROR(IIl) 


NAME 

ierror — catch Fortran errors 
SYNOPSIS 

if ( ierror ( errno ) .ne. 0 ) goto label 
DESCRIPTION 

terror provides a way of detecting errors during the running of a Fortran program Its argument 
is a run-lime error number such as enumerated in/c(I). 

When ierror is called, it returns a 0 value; thus the goto statement in the synopsis is not executed. 
However, the routine stores inside itself the call point and invocation level. If and when the in- 
dicated error occurs, a return is simulated from ierror with a non-zero value; thus the goto (or 
other statement) is executed. It is a ghastly error to call ierror from a subroutine which has al- 
ready returned when the error occurs. 

This routine is essentially tailored to catching end-of-file situations. Typically it is called just be- 
fore the start of the loop which reads the input file, and the goto jumps to a graceful termination 
of the program. 

There is a limit of 5 on the number of different error numbers which can be caught. 

SEE ALSO 

fc(I) 

BUGS 

There is no way to ignore errors. 
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LDI V (III ) 


5/7/73 


LDI V ( III ) 


NAME 

ldiv — long division 
SYNOPSIS 

ldiv(hidividend, lodividend, divisor) 
lrem(hidividend, lodividend, divisor) 

DESCRIPTION 

The concatenation of the signed 16-bit hidividend and the unsigned 16-bit lodividend is divided by 
divisor. The 16-bit signed quotient is returned by ldiv and the 16-bit signed remainder is returned 
by irem. Divide check and erroneous results will occur unless the magnitude of the divisor is 
greater than that of the high-order dividend. 

An integer division of an unsigned dividend by a signed divisor may be accomplished by 
quo = ldiv(0, dividend, divisor); 
and similarly for the remainder operation. 

Often both the quotient and the remainder are wanted. Therefore ldiv leaves a remainder in the 
external cell Idivr. 


BUGS 


No divide check check. 



LOCV(III) 


3/9/74 


LOCV(III) 


NAME 

locv — long output conversion 

SYNOPSIS 

char *locv(hi, lo) 
int hi, lo; 

DESCRIPTION 

Locv converts a signed double-precision integer, whose parts are passed as arguments, to the 
equivalent ASCII character string and returns a pointer lo that string. 


BUGS 



4/30/72 


LOG (III) 


LOG (III). 


I 

.NAME 

log — natural logarithm 

SYNOPSIS 

jsr rS,log 

double log(x) 
double x; ' 


DESCRIPTION 

The natural logarithm of frO is returned in frO. From C, the natural logarithm of x is returned. 


DIAGNOSTICS 

The error bit (c-bit) is set if the input argument is less than or equal to zero and the result is a 
negative number very large in magnitude. From C, there is no error indication. 






MONITOR (III) 


2/11/74 


MONITOR (III) 


NAME 

monitor — prepare execution profile 
SYNOPSIS 

monitorOowpc, highpc, buffer, bufsize) 
int lowpc( ), highpc( ), bufferl I, bufsize; 

DESCRIPTION 

Monitor is an interface to the system’s profile entry (II). Lowpc and highpc are the names of two 
functions; buffer is the address of a (user supplied) array of bufsize integers. Monitor arranges for 
the system to sample the user’s program counter periodically and record the execution histogram 
in the buffer. The lowest address sampled is that of lowpc and the highest is just below highpc. 
For the results to be significant, especially where there are small, heavily used routines, it is sug- 
gested that the buffer be no more than a few times smaller than the range of locations sampled. 

To profile the entire program, it is sufficient to use 
extern etext; 

monitor®, &etext, buf, bufsize); 

Etext is a loader-defined symbol which lies just above all the program text. 

To stop execution monitoring and write the results on the file mon.out, use 
monitor®); 

Then, when the program exits, prof (I) can be used to examine the results. 

It is seldom necessary to call this routine directly; the — p option of cc is simpler if one is 
satisfied with its default profile range and resolution. 

FILES 

mon.out 
err at QO 

prof (I), profit (II), cc (I) 



NARGS(III) 


5/10/73 


NARGS(III) 


NAME 

nargs — argument count 


SYNOPSIS 

nargs( ) 


DESCRIPTION 

Nargs returns the number of actual parameters supplied by the caller of the routine which calls 
nargs. 

The argument count is accurate only when none of the actual parameters is float ox double. Such 
parameters count as four arguments instead of one. 


BUGS 


As indicated. 



NLIST(III) 


6/12/72 


NLIST(III) 


NAME 

nlist — get entries from name list 
SYNOPSIS 

jsrr5,nlist; file; list 

file: < file name\0>; .even 

list: <namelxxx>; typel; valuel 
<name2xxx>; type2; value2 

0 

nlist(filename, nl) 
char *filename; 
struct { 

char name[81; 
int type; 

int value; 

} nil |; 

DESCRIPTION 

Nlist examines the name list in the given executable output file and selectively extracts a list of 
values. The name list consists of a list of 8-character names (null padded) each followed by two 
words. The list is terminated with a null name. Each name is looked up in the name list of the 
file- If the name is found, the type and value of the name are placed in the two words following 
the name. If the name is not found, the type entry is set to —1. 

This subroutine is useful for examining the system name list kept in the file /unix. In this way 
programs can obtain system addresses that are up to date. 

SEE ALSO 

a.out (V) 

DIAGNOSTICS 

All type entries are set to —1 if the file cannot be found or if it is not a valid namelist. 

BUGS 
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PERROR(III) 


11 / 5/73 


PERROR ( III ) 


NAME 

perror — system error messages 

SYNOPSIS 

perror(s) 
char *s; 

Int sys_nerr; 
char *sys_errlistU; 

int errno; 

DESCRIPTION 

Perror produces a short error message describing the last error encountered during a call to the 
system from a C program. First the argument string s is printed, then a colon, then the message 
and a new-line. Most usefully, the argument string is the name of the program which incurred 
the error. The error number is taken from the external variable errno, which is set when errors 
occur but not cleared when non-erroneous calls are made. 

To simplify variant formatting of messages, the vector of message strings sys_errlist is provided; 
errno can be used as an index in this table to get the message string without the newline. 
Sys_nerr is the largest message number provided for in the table; it should be checked because 
new error codes may be added to the system before they are added to the table. 

SEE ALSO 

Introduction to System Calls 


BUGS 



POW(III) 


4/30/73 


POW(III) 



• NAME 

pow — floating exponentiation 

SYNOPSIS 

movf x,frO 
movf y,frl 
jsr pc,pow 

double pow(x,y) 
double x, y; 

DESCRIPTION 

Pow returns the value of x y (in frO). Ppw(0, y) is 0 for any y. PowC—x, y) returns a result only if 
y is an integer. 

SEE ALSO 

expGil), logdll) 

DIAGNOSTICS 

The carry bit is set on return in case of overflow, pow(0, 0), or pow(—x, y) for non-integral y. 
From C there is no diagnostic. 

BUGS 
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PR I NTF ( III ) 


NAME 

prinlf— formatted print 

SYNOPSIS 

printf(format, arg ); 

char *format; 

DESCRIPTION 

Print/ converts, formats, and prints its arguments after the first under control of the first argu- 
ment. The first argument is a character string which contains two types of objects: plain charac- 
ters, which are simply copied to the output stream, and conversion specifications, each of which 
causes conversion and printing of the next successive argument to print/. 

Each conversion specification is introduced by the character %. Following the %, there may be. 

— an optional minus sign ” which specifies left adjustment of the converted argument in 
the indicated field; 

— an optional digit string specifying a field width; if the converted argument has fewer char- 
acters than the field width it will be blank-padded on the left (or right, if the left- 
adjustment indicator has been given) to make up the field width;. 

— an optional period which serves to separate the field width from the next digit string; 

— an optional digit string (precision) which specifies the number of digits to appear after the 
decimal point, for e- and f-conversion, or the maximum number of characters to be print- 
ed from a string; 

— a character which indicates the type of conversion to be applied. 

The conversion characters and their meanings are 

d 

0 

x The (integral) argument is converted to decimal, octal, or hexadecimal notation respective- 

l y - 

f The argument is converted to decimal notation in the style “[— Iddd.ddd” where the 
number of d’s after the decimal point is equal to the precision specification for the argu- 
ment. If the precision is missing, 6 digits are given; if the precision is explicitly 0, no di- 
gits and no decimal point are printed. The argument should be float or double. 

e The argument is converted in the style “[— ]d.ddde±dd” where there is one digit before 
the decimal point and the number after is equal to the precision specification for the 
argument; when the precision is missing, 6 digits are produced. The argument should be a 
float or double quantity. 

c The argument character or character-pair is printed if non-null. 

s The argument is taken to be a string (character pointer) and characters from the string are 
printed until a null character or until the number of characters indicated by the precision 
specification is reached; however if the precision is 0 or missing all characters up to a null 
are printed. 

1 The argument is taken to be an unsigned integer which is converted to decimal and print- 
ed (the result will be in the range 0 to 65535). 

If no recognizable character appears after the %, that character is printed; thus % may be printed 
by use of the siring %%. In no case does a non-existent or small field width cause truncation of 
a field; padding takes place only if the specified field width exceeds the actual width. Characters 
generated by print f are printed by calling putchar. 

SEE ALSO 

putchar (III) 




PUTC(III) 
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PUTC(IIl) 



NAME 

putc — buffered output 
SYNOPSIS 

mov $filename,r0 

jsr r5,fcreat; iobuf 

fcreafffile, iobuf) 
char *file; 
struct buf * iobuf; 

(get byte in rO) 

jsr r5,putc; iobuf 

putc(c, iobuf) 

int c; 

struct buf * iobuf; 

(get word in rO) 
jsr r5,putw; iobuf 

putw(w, iobuf); 
int w; 

struct buf * iobuf; 

jsr r5,flush; iobuf 

fflush(iobuf) 
struct buf * iobuf; 

DESCRIPTION 

Fcrear creates the given file (mode 666) and sets up the buffer iobuf ( size 518 bytes); pure and putw 
write a byte or word respectively onto the file; flush forces the contents of the buffer to be writ- 
ten, but does not close the file. The format of the buffer is: 

iobuf: .=.+2 / file descriptor 

.=.+2 / characters unused in buffer 

.=.+2 / ptr to next free character 

.=.+512. / buffer 

Or in C, 

struct buf { 

int Aides; 
int nunused; 
char *nxtfree; 
char buff]512l; 

}; 

Fcrear sets the error bit (c-bit) if the file creation failed (from C, returns -1); none of the other 
routines returns error information. 

Before terminating, a program should call flush to force out the last of the output (fflush from C). 
The user must supply iobuf, which should begin on a word boundary. 

To write a new file using the same buffer, it suffices to call i ffflush , close the file, and call fcrear 
again. 

SEE ALSO 

creat(II), write(II), getc(III) 

DIAGNOSTICS 

error bit possible on fcrear call. 




PUTCHAR(III) 
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PUTCHAR (III) 


NAME 

putchar — write character 

SYNOPSIS 

putchar(ch) 

flush( ) 

DESCRIPTION 

Putchar writes out its argument and returns it unchanged. Only the low-order byte is written, 
and only if it is non-null. Unless other arrangements have been made, putchar writes in 
unbuffered fashion on the standard output file. 

Associated with this routine is an external variable /out which has the structure of a buffer dis- 
cussed under pule (III). If the file descriptor part of this structure (first word) is greater than 2, 
output via putchar is buffered. To achieve buffered output one may say, for example, 

fout = dup(l); or • 

fout = creatC. .); 

In such a case flush must be called before the program terminates in order to flush out the 
buffered output. Flush may be called at any time. 

SEE ALSO 

putc(III) 

BUGS 

The fout notion is kludgy. 



PUTC(III) 


6/12/72 


PUTC(III) 


NAME 

putc — buffered output 
SYNOPSIS 

mov $filename,rf) 

jsr r5,fcreat; iobuf 

fcreat(file, iobuf) 
char *file; 
struct buf *iobuf; 

(get byte in rO) 

jsr r5,putc; iobuf 

putc(c, iobuO 
int c; 

struct buf *iobuf; 

(get word in rO) 
jsr r5,putw; iobuf 

putw(w, iobuf); 
int w; 

struct buf *iobuf; 

jsr r5,flush; iobuf 

fflush(iobuf) 
struct buf *iobuf; 

DESCRIPTION 

Fcreat creates the given file (mode 666) and sets up the buffer iobuf (size 518 bytes); putc and putw 
write a byte or word respectively onto the file; .flush forces the contents of the buffer to be writ- 
ten, but does not close the file. The format of the buffer is; 


iobuf: .=.+2 

/ file descriptor 

.=.+2 

/ characters unused in buffer 

.=.+2 

/ ptr to next free character 

.=.+512. 

/ buffer 

Or in C, 


struct buf { 


int fildes; 


int nunused; 


char *nxtfree; 


char buffl5121; 



); 


Fcreat sets the error bit (c-bil) if the file creation failed (from C, returns —1); none of the other 
routines returns error information. 

Before terminating, a program should call . flush to force out the last of the output (/flush from C). 
The user must supply iobuf which should begin on a word boundary. 

To write a new file using the same buffer, it suffices to call [fjflush, close the file, and call fcreat 
again. 

SEE ALSO 

creat(Il), writeGI), getc(III) 

DIAGNOSTICS 

error bit possible on fcreat call. 
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5/10/73 


PUTCHAR (111) 


NAME 

putchar — write character 

SYNOPSIS 

putchar(ch) 

flush( ) 

DESCRIPTION 

Putchar writes out its argument and returns it unchanged. Only the low-order byte is written, 
and only if it is non-null. Unless other arrangements have been made, putchar writes in 
unbuffered fashion on the standard output file. 

Associated with this routine is an external variable four which has the structure of a buffer dis- 
cussed under putc (III). If the file descriptor part of this structure (first word) is greater than 2, 
output via putchar is buffered. To achieve buffered output one may say, for example, 

fout = dup(l>, or 

foul = creat(...>. 

In such a case flush must be called before the program terminates in order to flush out the 
buffered output. Flush may be called at any time. 

SEE ALSO 

putc(III) 

BUGS 

The fout notion is kludgy. 



QSORT(III) 
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QSORT(III) 


NAME 

qsort — quicker sort 
SYNOPSIS 

(base of data in rl) 

(end+1 of data in r2) 

(element width in r3) 
jsr pc, qsort 

qsort(base, nel, width, compar) 
char *base; 
int (*comparX ); 

DESCRIPTION 

Qsort is an implementation of the quicker-sort algorithm. The assembly-language version is 
designed to sort equal length elements. Registers rl and r2 delimit the region of core containing 
the array of byte strings to be sorted: rl points to the start of the first siring, r2 to the first loca- 
tion above the last string. Register r3 contains the length of each string. r2 — r 1 should be a mul- 
tiple of r3. On return, rO, rl, r2, r3 are destroyed. 

The C version has somewhat different arguments and the user must supply a comparison 
routine. The first argument is to the base of the data; the second is the number of elements; the 
third is the width of an element in bytes; the last is the name of the comparison routine. It is 
called with two arguments which are pointers to the elements being compared. The routine must 
return a negative integer if the first element is to be considered less than the second, a positive 
integer if the second element is smaller than the first, and 0 if the elements are equal. 

SEE ALSO 

sort (I) . 

BUGS 
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RAND(IU) 


NAME 

rand — random number generator 

SYNOPSIS • 

(seed in rO) 

jsr pc,srand /to initialize 

jsr pc,rand /to get a random number 

srand(seed) • 
int seed; 

rand( ) 

DESCRIPTION • 

Rand uses a multiplicative congruential random number generator to return successive pseudo- 
random numbers (in rO) in the range from 1 to 2 15 — 1. 

The generator is reinitialized by calling srand with 1 as argument (in rO). It can be set to a ran- 
dom starting point by calling srand with whatever you like as argument, for example the low- 
order word of the time. 

BUGS 

The low-order bits are not very random. 



RESET (III) 
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RESET (III) 


NAME 

reset — execute non-local goto 

SYNOPSIS 

setexit( ) 

reseK ) 

DESCRIPTION 

These routines are useful for dealing with errors discovered in a low-level subroutine of a pro- 
gram. 

Setexit is typically called just at the start of the main loop of a processing program. It stores cer- 
tain parameters such as the call point and the stack level. 

Reset is typically called after diagnosing an error in some subprocedure called from the main 
loop. When reset is called, it pops the stack appropriately and generates a non-local return from 
the last call to setexit. 

It is erroneous, and generally disastrous, to call reset unless setexit has been called in a routine 
which is an ancestor of reset. 


BUGS 


SETFIL(III) 
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SETFIL(III) 


NAME 

setfil — specify Fortran file name 
SYNOPSIS 

call setfil ( unit, hoilerith-string ) 


DESCRIPTION 

Setfil provides a primitive way to associate an integer I/O unit number with a file named by the 
hoilerith-string. The end of the file name is indicated by a blank. Subsequent I/O on this unit 
number will refer to the file whose name is specified by the string. 

Setfil should be called only before any I/O has been done on the unit, or just after doing a rewind 
or endfile. It is ineffective for unit numbers 5 and 6. 


SEE ALSO 

fc(I) 


BUGS 


The exclusion of units 5 and 6 is unwarranted. 



SIN (III) 
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SIN (III) 


NAME 

sin — sine, cosine 

SYNOPSIS 

jsr r5,sin (cos) 

double sin(x) 
double x; 

double cos(x) 
double x; 

DESCRIPTION 

The sine (cosine) of frO (resp. x), measured in radians, is returned (in frO). 

The magnitude of the argument should be checked by the caller to make sure the result is mean- 
ingful. 

BUGS 
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SQRT(III) 


NAME 

sqrt — square root function 

SYNOPSIS 

jsr r5,sqrt 

double sqrt(x) 
double x; 

DESCRIPTION 

The square root of frO (resp. x) is returned (in frO). 

DIAGNOSTICS 

The c-bit is set on negative arguments and 0 is returned. There is no error return for C pro- 
grams. 

BUGS 

No error return from C. , 



TTYN(III) 


1/15/73 


TTYN(III) 


NAME 

ttyn — return name of current typewriter 

SYNOPSIS 

jsr pc, ttyn 

ttyn(file) 

DESCRIPTION 

Ttyn hunts up the last character of the name of the typewriter which is the standard input (from 
as) or is specified by the argument file descriptor (from C). If n is returned, the typewriter name 
is then “/dev/tty/j”. . 

x is returned if the indicated file does not correspond to a typewriter. 



VT(III) 
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VT(III) 


NAME 

vt — display (vtOl) interface 

SYNOPSIS 

openvt( ) 

erase( ) 

label(s) 
char si 1; 

line{x,y) 

circle(x,y,r) 

arc(x,y,xO,yO,xl,yl) 

. dot(x,y,dx,n,pattern) 
int pattern! I ; 

move(x,y) 

DESCRIPTION 

C interface routines to perform similarly named functions described in vl(IV). Openvt must be 
... used before any of the others to open the storage scope for writing. 

FILES 

/dev/vtO, found in /lib/libp.a 

SEE ALSO 

Vt (IV) 


BUGS 
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9/10/73 


ARCHIVE(V) 


NAME 

archive (library) file format 


DESCRIPTION 

The archive command ar is used to combine several files into one. Archives are used mainly as 
libraries to be searched by the link-editor Id. 

A file produced by ar has a magic number at the start, followed by the constituent files, each pre- 
ceded by a file header. The magic number is 177555(8) (it was chosen to be unlikely to occur 
anywhere else). The header of each file is 16 bytes long: 

0-7 file name, null padded on the right 
8-11 modification time of the file 

12 user ID of file owner 

13 file mode 

14-15 file size _ ' 

If the file is an odd number of bytes long, it is padded with a null byte, but the size in the header 
is correct. 

Notice there is no provision for empty areas in an archive file. . 


SEE ALSO 

ar. Id (I) 


BUGS 

Names are only 8 characters, not 14. More important, there isn’t enough room to store the prop- 
er mode, so ar always extracts in mode 666. 
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CORE(V) 


NAME 

core — format of core image file 
DESCRIPTION 

UNIX writes out a core image of a terminated process when any of various errors occur. See sig- 
nal (ID for the list of reasons; the most common are memory violations, illegal instructions, bus 
errors, and user-generated quit signals. The core image is called “core” and is written in the 
process’s working directory (provided it can be; normal access controls apply). 

The first 1024 bytes of the core image are a copy of the system’s per-user data for the process, 
including the registers as they were at the time of the fault. The remainder represents the actual 
contents of the user's core area when the core image was written. At the moment, if the text 
segment is write-protected and shared, it is not dumped; otherwise the entire address space is 
dumped. 

The actual format of the information in the first 1024 bytes is complicated. A guru will have to 
be consulted if enlightenment is required. In general the debugger db (7/ should be used to deal 
with core images. • . 

SEE ALSO 

db (I), signal (II) 



DIRECTORY ( V ) 
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DIRECTORY (V) 



NAME 

format of directories 
DESCRIPTION 

A directory behaves exactly like an ordinary file, save that no user may write into a directory. 
The fact that a file is a directory is indicated by a bit in the flag word of its i-node entry. Direc- 
tory entries are 16 bytes long. The first word is the i-number of the file represented by the entry, 
if non-zero; if zero, the entry is empty. 

Bytes 2-15 represent the (14-character) file name, null padded on the right. These bytes are not 
cleared for empty slots. 

By convention, the first two entries in each directory are for and The first is an entry 
for the directory itself. The second is for the parent directory. The meaning of is modified 
for the root directory of the master file'system and for the root directories of removable file sys- • 
terns. In the first case, there is no parent, and in the second, the system does not permit off- 
device references. Therefore in both cases has the same meaning as 

SEE ALSO 

file system (V) 
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FILE SYSTEM (V) 


NAME 

fs — formal of file system volume 
DESCRIPTION 

Every file system storage volume (e.g. RF disk, RK disk, RP disk, DECtape reel) has a common 
format for certain vital information. Every such volume is divided into a certain number of 256 
word (512 byte) blocks. Block 0 is unused and is available to contain a bootstrap program, pack 
label, or other information. 

Block 1 is the super block. Starting from its first word, the format of a super-block is 
struct { 


ini 

isize; 

int 

fsize; 

ini 

nfree; 

int 

free[100]; 

int 

ninode; 

int 

inode[100]; 

char 

flock; 

char 

ilock; 

char 

fmod; 

int 

time[2]; 


}; 

/size" is the number of blocks devoted to the i-list, which starts just after the super-block, in block 
2. Fsize is the first block not potentially available for allocation to a file. This number is unused 
by the system, but is used by programs like check (I) to test for bad block numbers. The free list 
for each volume is maintained as follows. The free array contains, in freetl], . , free[nfree—l ] 
up to 99 numbers *of free blocks. Free[0] is the block number of the head of a chain of blocks 
constituting the free list. The first word in each free-chain block is the number (up to 100) of 
free-block numbers listed in the next 100 words of this chain member. The first of these 100 
blocks is the link to the next member. of the chain. To allocate a block: decrement nfree. and the 
new block is freetnfree]. If the new block number is 0, there are no blocks left, so give an error. 
If nfree became 0, read in the block named by the new block number, replace nfree by its first 
word, and copy the block numbers in the next 100 words into the free array. To free a block, 
check if nfree is 100; if so, copy nfree and the free array into it, write it out, and set nfree to 0. In 
any event set ,free[nfree] to the freed block’s number and increment nfree. 

Ninode is the number of free i-numbers in the inode array. To allocate an i-node: if ninode is 
greater than 0, decrement it and return inode[ninodeJ. If it was 0, read the i-list and place the 
numbers of all free inodes (up to 100) into the inode array, then try again. To free an i-node, pro- 
vided ninode is less than 100, place its number into inode[ninode] and increment ninode. If ninode 
is already 100, don’t bother to enter the freed i-node into any table. This list of i-nodes is only 
to speed up the allocation process; the information as to whether the inode is really free or not is 
maintained in the inode itself. 

Flock and Hock are flags maintained in the core copy of the file system while it is mounted and 
their values on disk are immaterial. The value of / mod on disk is likewise immaterial; it is used 
as a flag to indicate that the super-block has changed and should be copied to the disk during the 
next periodic update of file system information. 

Time is the last time the super -block of the file system was changed, and is a double-precision 
representation of the number of seconds that have elapsed since 0000 Jan. 1 1970 (GMT). Dur- 
ing a reboot, the rime of the super-block for the root file system is used to set the system’s idea 
of the time. 

I-numbers begin at 1, and the storage for i-nodes begins in block 2. Also, i-nodes are 32 bytes 
long, so 16 of them fit into a block. Therefore, i-node / is located in block (/' + 31)/ 16, and be- 
gins 32 ’((/' + 31) (mod 16) bytes from its start. I-node 1 is reserved for the root directory of the 
file system, but no other i-number has a built-in meaning. Each i-node represents one file. The 
formal of an i-node is as follows. 
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TP(V) 


name ' 

tp - DEC/mag tape formats , 

DESCRIPTION comniand (p dumps and extr acts files to and DECtape and magtape. The formats of these 
tapes are the same except that magtapes have larger directories. 

Block zero contains a copy of a stand-alone bootstrap program. See boot procedures (VIII). 

Blocks 1 through 24 for DECtape (1 through 62 for magtape) contain a directory of the tape. 
There are 192 (resp. 496) entries in the directory; 8 entries per block; 64 bytes per entry. Each 
entry has the following format: 

path name 32 bytes 

mode 2 bytes 

uid 1 byte ' ' 

gid 1 byte - . . , . 

unused 1 byte 

size 3 bytes 

time modified 4 bytes 

tape address 2 bytes 

unused 16 bytes 

check sum 2 bytes 

Thfe path name entry is the path name of the file when put on the tape. If the pathname starts 
with a zero word, the entry is empty. It is at most 32 bytes long and ends in a null byte. Mode, 
* uid^ gid, size and time modified are the same as described under i-nodes (file system (V)). The 

tape address is the tape block number of the start of the contents of the file. Every file starts on 
a block boundary. The file occupies (size+511)/512 blocks of continuous tape. The checksum en- 
try has a value such that the sum of the 32 words of the directory entry is zero. 

Blocks 25 (resp. 63) on are available for file storage. 

A fake entry (see tp(I)) has a size of zero. 

SEE ALSO 

file system(V), tp(I) 






